33353ce62b
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Local adapters (Claude, Codex, Cursor, Gemini, Grok, OpenCode, Pi, ACPX) ship bundled "skills" — opinionated Markdown prompt bundles materialized into the agent's runtime > - One of those bundled skills, `paperclip-dev`, existed to let agents develop Paperclip itself; it has now moved to its own external repo and no longer belongs in the core tree > - The adapter skill model also carried a `required` / `requiredReason` attribute plus a `paperclip_required` `AdapterSkillOrigin` variant, all of which only existed to mark bundled skills as non-optional in the UI and adapter sync logic > - With `paperclip-dev` gone, no bundled skill is "required" anymore, and the type / runtime surface for `required` is dead weight — but it is computed at request time and never persisted, so a clean removal is safe (no compatibility shim needed) > - This pull request deletes `skills/paperclip-dev/` and removes every trace of the `required` / `requiredReason` field and the `paperclip_required` origin across shared types, validators, adapter-utils, all eight local adapters, server routes, the company-skills service, the UI, the storybook fixtures, and the test suite > - The benefit is a smaller, simpler adapter-skill surface: one origin (`company_managed`) for managed bundled skills, `resolvePaperclipDesiredSkillNames` collapses to "just the configured desired set", and the AgentDetail skills tab no longer renders a "Required by Paperclip" section that no longer applies ## Linked Issues or Issue Description <!-- No existing public GitHub issue; describing the underlying work inline (feature_request template fields). --> **Summary** Remove the bundled `paperclip-dev` skill (now maintained in its own external repo) and retire the `required` / `requiredReason` skill attribute and the `paperclip_required` skill origin, which only existed to support it. **Problem or motivation** `paperclip-dev` is the only bundled skill that was ever marked "required". Now that it lives in a separate repository, shipping it inside the core tree is wrong, and the entire `required` surface (a type field, a validator field, a synthesized `paperclip_required` origin, UI "Required by Paperclip" section, and required-skill merging in the desired-skills calculation) becomes dead weight. The `required` value is computed at request time and never persisted, so it can be removed cleanly without a migration or compatibility shim. **Proposed solution** Delete `skills/paperclip-dev/`, drop the `required` / `requiredReason` fields and `paperclip_required` origin everywhere they are produced or consumed, collapse managed-skill origin to a single `company_managed` value, and simplify `resolvePaperclipDesiredSkillNames` to return only the configured desired set. **Alternatives considered** Keeping the `required` attribute as a no-op for forward compatibility — rejected because it is request-time only (nothing persists it), so leaving it in place is pure dead surface area with no callers. **Roadmap alignment** Internal cleanup / dead-code removal that simplifies the adapter-skill surface; it does not introduce or duplicate any planned core feature in ROADMAP.md. ## What Changed - Deleted bundled `skills/paperclip-dev/` (moved to a separate repo). - Dropped `required`, `requiredReason`, and the `paperclip_required` origin from `packages/shared/src/types/adapter-skills.ts`, `packages/shared/src/validators/adapter-skills.ts`, and `packages/adapter-utils/src/types.ts`. - In `packages/adapter-utils/src/server-utils.ts`: removed `readSkillRequired()`; dropped `required`/`requiredReason` from `listPaperclipSkillEntries()`, `normalizeConfiguredPaperclipRuntimeSkills()`, `buildPersistentSkillSnapshot()`, and `PaperclipSkillEntry`; collapsed `buildManagedSkillOrigin()` to always return `company_managed`; simplified `resolvePaperclipDesiredSkillNames()` to return only the configured desired set (signature preserved so adapter call sites are untouched). - Walked all eight local adapters (`acpx-local`, `claude-local`, `codex-local`, `cursor-local`, `gemini-local`, `grok-local`, `opencode-local`, `pi-local`) and removed every remaining `requiredReason` / `paperclip_required` reference. - `server/src/services/company-skills.ts`: dropped the `required = sourceKind === "paperclip_bundled"` synthesis when listing runtime skill entries. - `server/src/routes/agents.ts`: removed required-skill merging from the desired-skills calculation in the persist-config path and the unsupported-snapshot path (keeping the current version-aware `desiredSkillEntries` structure). - `ui/src/pages/AgentDetail.tsx`: dropped required-based filters, the required tooltip, and the entire "Required by Paperclip" section from the agent skills tab; storybook fixtures in `ui/storybook/stories/acpx-local.stories.tsx` cleaned up to match. - Tests: deleted the `required: false` case in `paperclip-skill-utils.test.ts` and the "keeps required bundled skills installed" case in every `*-local-skill-sync.test.ts`; `acpx-local-execute.test.ts`, `cursor-local-execute.test.ts`, `cursor-local-skill-sync.test.ts`, `agent-skills-routes.test.ts`, and `packages/adapter-utils/src/server-utils.test.ts` were updated to drop removed fields and map `origin: "paperclip_required"` → `"company_managed"`. - `server/src/adapters/registry.ts`: two `as unknown as ServerAdapterModule["..."]` casts on `hermesListSkills` / `hermesSyncSkills` (matching the existing `executeHermesLocal` pattern). `hermes-paperclip-adapter@0.2.0` still depends on the published `@paperclipai/adapter-utils` which keeps the retired `paperclip_required` variant; the cast bridges the workspace-vs-published type mismatch at the registry seam and can drop once hermes upgrades. ## Verification Run from the workspace root: ```sh grep -rn "skills/paperclip-dev" . grep -rn "paperclip_required" --include="*.ts" --include="*.tsx" . grep -rn "requiredReason" --include="*.ts" --include="*.tsx" . pnpm -w typecheck pnpm --filter @paperclipai/server exec vitest run paperclip-skill-utils pnpm --filter @paperclipai/server exec vitest run skill-sync ``` The first three greps return only the explanatory comment in `server/src/adapters/registry.ts` (no live `paperclip_required` / `requiredReason` usage) and zero `skills/paperclip-dev` source hits. Locally: - `pnpm -w typecheck` → all packages this PR touches pass (adapter-utils, shared, server, ui, cli, and the cursor/gemini/opencode/pi adapters). - Affected vitest suites pass: `paperclip-skill-utils`, `server-utils`, all eight `*-local-skill-sync`, `agent-skills-routes`, and the `acpx`/`cursor`/`pi` execute suites. ## Risks - Behavioral shift in the agent skills UI: the "Required by Paperclip" section disappears. No bundled skill is required anymore, so this only affects environments that previously surfaced `paperclip-dev` as a forced-on row; those installs will see the skill move into the regular "company-managed" list (and be uninstalled on next sync unless explicitly listed as desired). - Existing agents may still have the string `"paperclip-dev"` in their persisted `desiredSkills`. That entry is inert (no source for it to install from); a one-time DB cleanup is out of scope. Low risk. - Hermes adapter type bridge: two casts in `registry.ts` paper over a type-only divergence between the workspace `@paperclipai/adapter-utils` and the published version still pinned by `hermes-paperclip-adapter@0.2.0`. Runtime behavior is unaffected because the retired `paperclip_required` value is no longer produced by anything in this tree. The casts can be removed once hermes upgrades its dependency. ## Model Used - Provider: Anthropic - Model: Claude Opus 4.7 (`claude-opus-4-7`) - Capability: agent tool use via Paperclip's `claude_local` adapter ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
904 lines
27 KiB
TypeScript
904 lines
27 KiB
TypeScript
import { useMemo, useState, type ReactNode } from "react";
|
|
import type { Meta, StoryObj } from "@storybook/react-vite";
|
|
import { useQueryClient } from "@tanstack/react-query";
|
|
import type { AdapterConfigSchema, CreateConfigValues } from "@paperclipai/adapter-utils";
|
|
import { parseAcpxStdoutLine } from "@paperclipai/adapter-acpx-local/ui";
|
|
import type {
|
|
Agent,
|
|
AgentSkillSnapshot,
|
|
CompanySkillListItem,
|
|
} from "@paperclipai/shared";
|
|
import { SchemaConfigFields } from "@/adapters/schema-config-fields";
|
|
import type { TranscriptEntry } from "@/adapters";
|
|
import { RunTranscriptView } from "@/components/transcript/RunTranscriptView";
|
|
import { AgentSkillsTab } from "@/pages/AgentDetail";
|
|
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
|
|
import { Badge } from "@/components/ui/badge";
|
|
import { queryKeys } from "@/lib/queryKeys";
|
|
|
|
type SchemaWindow = typeof window & {
|
|
__paperclipStorybookAdapterSchemas?: Record<string, unknown>;
|
|
};
|
|
|
|
// Mirrors packages/adapters/acpx-local/src/server/config-schema.ts. Inlined so the
|
|
// storybook bundle does not pull node-only imports from the adapter server entry.
|
|
const acpxLocalConfigSchema: AdapterConfigSchema = {
|
|
fields: [
|
|
{
|
|
key: "agent",
|
|
label: "ACP agent",
|
|
type: "select",
|
|
default: "claude",
|
|
required: true,
|
|
options: [
|
|
{ value: "claude", label: "Claude via ACPX" },
|
|
{ value: "codex", label: "Codex via ACPX" },
|
|
{ value: "custom", label: "Custom ACP command" },
|
|
],
|
|
hint: "Choose the ACP agent launched through ACPX.",
|
|
},
|
|
{
|
|
key: "agentCommand",
|
|
label: "Agent command",
|
|
type: "text",
|
|
hint: "Required for custom agents; optional override for built-in Claude or Codex ACP commands.",
|
|
},
|
|
{
|
|
key: "nonInteractivePermissions",
|
|
label: "Non-interactive permissions",
|
|
type: "select",
|
|
default: "deny",
|
|
options: [
|
|
{ value: "deny", label: "Deny" },
|
|
{ value: "fail", label: "Fail" },
|
|
],
|
|
hint: "Fallback if the ACP agent asks for input outside an interactive session. Paperclip still auto-approves permissions by default.",
|
|
},
|
|
{
|
|
key: "cwd",
|
|
label: "Working directory",
|
|
type: "text",
|
|
hint: "Absolute fallback directory. Paperclip execution workspaces can override this at runtime.",
|
|
},
|
|
{
|
|
key: "stateDir",
|
|
label: "State directory",
|
|
type: "text",
|
|
hint: "Optional ACPX session state directory. Defaults to Paperclip-managed company/agent scoped storage.",
|
|
},
|
|
{
|
|
key: "fastMode",
|
|
label: "Codex fast mode",
|
|
type: "toggle",
|
|
default: false,
|
|
hint: "Only applies when ACP agent is Codex. Requests Codex Fast mode through ACP session config.",
|
|
meta: { visibleWhen: { key: "agent", values: ["codex"] } },
|
|
},
|
|
{ key: "timeoutSec", label: "Timeout seconds", type: "number", default: 0 },
|
|
{
|
|
key: "warmHandleIdleMs",
|
|
label: "Warm process idle ms",
|
|
type: "number",
|
|
default: 0,
|
|
hint: "Defaults to 0, which closes the ACPX process after each run while retaining persistent session state.",
|
|
},
|
|
{
|
|
key: "env",
|
|
label: "Environment JSON",
|
|
type: "textarea",
|
|
hint: "Optional JSON object of environment values or secret bindings.",
|
|
},
|
|
],
|
|
};
|
|
|
|
function installAcpxSchemaMock(): void {
|
|
if (typeof window === "undefined") return;
|
|
const win = window as SchemaWindow;
|
|
win.__paperclipStorybookAdapterSchemas = {
|
|
...(win.__paperclipStorybookAdapterSchemas ?? {}),
|
|
acpx_local: acpxLocalConfigSchema,
|
|
};
|
|
}
|
|
|
|
function ConfigSection({ title, description, children }: { title: string; description?: string; children: ReactNode }) {
|
|
return (
|
|
<Card className="shadow-none border-border">
|
|
<CardHeader>
|
|
<CardTitle className="text-base font-semibold">{title}</CardTitle>
|
|
{description && (
|
|
<p className="text-sm text-muted-foreground">{description}</p>
|
|
)}
|
|
</CardHeader>
|
|
<CardContent>
|
|
<div className="space-y-3">{children}</div>
|
|
</CardContent>
|
|
</Card>
|
|
);
|
|
}
|
|
|
|
function AcpxLocalConfigStory() {
|
|
installAcpxSchemaMock();
|
|
|
|
const [values, setValues] = useState<CreateConfigValues>(() => ({
|
|
name: "",
|
|
role: "",
|
|
title: "",
|
|
capabilities: "",
|
|
icon: "code",
|
|
adapterType: "acpx_local",
|
|
command: "",
|
|
promptTemplate: "",
|
|
bootstrapPromptTemplate: "",
|
|
instructionsFilePath: "",
|
|
extraArgs: "",
|
|
envVars: "",
|
|
envBindings: {},
|
|
runtimeServicesJson: "",
|
|
runtimeDesiredState: "manual",
|
|
runtimeServiceStates: {},
|
|
heartbeatEnabled: false,
|
|
intervalSec: 900,
|
|
wakeOnDemand: true,
|
|
cooldownSec: 60,
|
|
maxConcurrentRuns: 1,
|
|
pauseOnIdle: false,
|
|
idleTimeoutSec: 0,
|
|
runtimeMaxStuckHeartbeats: 0,
|
|
adapterSchemaValues: {},
|
|
} as unknown as CreateConfigValues));
|
|
|
|
return (
|
|
<div className="mx-auto max-w-3xl space-y-5 p-6">
|
|
<header className="space-y-2">
|
|
<Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
|
|
UX preview
|
|
</Badge>
|
|
<h1 className="text-2xl font-semibold tracking-tight">Agent config — acpx_local</h1>
|
|
<p className="text-sm text-muted-foreground">
|
|
Renders the schema-driven adapter config block exactly as the operator sees it inside the agent edit form.
|
|
Defaults reflect Phase 3 of PAP-2944: maximum-permission auto-approve, persistent session mode, Claude as the
|
|
default ACP agent.
|
|
</p>
|
|
</header>
|
|
|
|
<ConfigSection
|
|
title="Adapter configuration"
|
|
description="Schema fields rendered through the generic SchemaConfigFields component."
|
|
>
|
|
<SchemaConfigFields
|
|
mode="create"
|
|
isCreate
|
|
adapterType="acpx_local"
|
|
values={values}
|
|
set={(patch) => setValues((current) => ({ ...current, ...patch }))}
|
|
config={{}}
|
|
eff={(_group, _field, original) => original}
|
|
mark={() => {}}
|
|
models={[]}
|
|
/>
|
|
</ConfigSection>
|
|
|
|
<ConfigSection title="Resolved values (debug)">
|
|
<pre className="whitespace-pre-wrap text-xs font-mono text-muted-foreground">
|
|
{JSON.stringify(values.adapterSchemaValues ?? {}, null, 2)}
|
|
</pre>
|
|
</ConfigSection>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
const ACPX_TS_BASE = new Date("2026-04-30T15:30:00.000Z").getTime();
|
|
|
|
function ts(offsetMs: number): string {
|
|
return new Date(ACPX_TS_BASE + offsetMs).toISOString();
|
|
}
|
|
|
|
function flattenLines(lines: Array<{ payload: Record<string, unknown>; offsetMs: number }>): TranscriptEntry[] {
|
|
const entries: TranscriptEntry[] = [];
|
|
for (const { payload, offsetMs } of lines) {
|
|
const parsed = parseAcpxStdoutLine(JSON.stringify(payload), ts(offsetMs));
|
|
entries.push(...parsed);
|
|
}
|
|
return entries;
|
|
}
|
|
|
|
function useAcpxTranscript(): TranscriptEntry[] {
|
|
return useMemo(
|
|
() =>
|
|
flattenLines([
|
|
{
|
|
offsetMs: 0,
|
|
payload: {
|
|
type: "acpx.session",
|
|
agent: "claude",
|
|
mode: "persistent",
|
|
permissionMode: "approve-all",
|
|
acpSessionId: "acp_session_42a8c1",
|
|
runtimeSessionName: "acpx-claude-PAP-1812",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 800,
|
|
payload: {
|
|
type: "acpx.status",
|
|
tag: "context_window",
|
|
used: 12000,
|
|
size: 200000,
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 1200,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text: "Looking at the failing test in `runtime-state.test.ts` — ",
|
|
channel: "thought",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 1500,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text: "the assertion expects `pendingRestart` but the new state machine uses `restartScheduled`.\n",
|
|
channel: "thought",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 1900,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text: "I'll inspect the test file to confirm the change.\n\n",
|
|
channel: "output",
|
|
tag: "agent_message_chunk",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 2200,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "read",
|
|
toolCallId: "tool_read_01",
|
|
status: "running",
|
|
text: "server/src/runtime-state.test.ts",
|
|
input: { path: "server/src/runtime-state.test.ts" },
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 3500,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "read",
|
|
toolCallId: "tool_read_01",
|
|
status: "completed",
|
|
text: "Read 142 lines",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 3700,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text:
|
|
"The test still references the old `pendingRestart` field. I'll update the assertion to use the renamed `restartScheduled` flag.\n\n",
|
|
channel: "output",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 4200,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "edit",
|
|
toolCallId: "tool_edit_02",
|
|
status: "running",
|
|
input: {
|
|
path: "server/src/runtime-state.test.ts",
|
|
find: "expect(state.pendingRestart).toBe(true)",
|
|
replace: "expect(state.restartScheduled).toBe(true)",
|
|
},
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 5400,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "edit",
|
|
toolCallId: "tool_edit_02",
|
|
status: "completed",
|
|
text: "1 replacement",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 5800,
|
|
payload: {
|
|
type: "acpx.status",
|
|
text: "Running vitest for runtime-state.test.ts",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 6100,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "command",
|
|
toolCallId: "tool_run_03",
|
|
status: "running",
|
|
input: { command: "pnpm exec vitest run server/src/runtime-state.test.ts" },
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 9100,
|
|
payload: {
|
|
type: "acpx.tool_call",
|
|
name: "command",
|
|
toolCallId: "tool_run_03",
|
|
status: "completed",
|
|
text:
|
|
"Test Files 1 passed (1)\nTests 6 passed (6)\nDuration 2.31s",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 9400,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text:
|
|
"**Test passes.** Updated `runtime-state.test.ts` to assert against `restartScheduled` instead of the renamed `pendingRestart` field.\n\n",
|
|
channel: "output",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 9600,
|
|
payload: {
|
|
type: "acpx.text_delta",
|
|
text:
|
|
"Next I'll update the issue with a summary and hand it back to QA for verification.",
|
|
channel: "output",
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 9800,
|
|
payload: {
|
|
type: "acpx.status",
|
|
tag: "context_window",
|
|
used: 18450,
|
|
size: 200000,
|
|
},
|
|
},
|
|
{
|
|
offsetMs: 10000,
|
|
payload: {
|
|
type: "acpx.result",
|
|
summary: "completed",
|
|
stopReason: "end_turn",
|
|
inputTokens: 18450,
|
|
outputTokens: 412,
|
|
cachedTokens: 12000,
|
|
costUsd: 0.024,
|
|
subtype: "end_turn",
|
|
},
|
|
},
|
|
]),
|
|
[],
|
|
);
|
|
}
|
|
|
|
function AcpxLocalTranscriptStory() {
|
|
const entries = useAcpxTranscript();
|
|
|
|
return (
|
|
<div className="mx-auto max-w-4xl space-y-5 p-6">
|
|
<header className="space-y-2">
|
|
<Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
|
|
UX preview
|
|
</Badge>
|
|
<h1 className="text-2xl font-semibold tracking-tight">Run transcript — acpx_local streamed events</h1>
|
|
<p className="text-sm text-muted-foreground">
|
|
Demonstrates how a streamed acpx_local run renders through the existing transcript pipeline. Events flow
|
|
through <code>parseAcpxStdoutLine</code> (session init, thought delta, assistant delta, tool call/result
|
|
pairs, context window status, final result) and into <code>RunTranscriptView</code> in nice mode.
|
|
</p>
|
|
</header>
|
|
|
|
<Card className="shadow-none border-border overflow-hidden">
|
|
<CardHeader>
|
|
<CardTitle className="text-base font-semibold">Run Transcript (nice mode)</CardTitle>
|
|
<p className="text-xs text-muted-foreground">
|
|
Streaming, comfortable density. Mirrors the agent detail page transcript surface.
|
|
</p>
|
|
</CardHeader>
|
|
<CardContent>
|
|
<RunTranscriptView entries={entries} mode="nice" density="comfortable" streaming />
|
|
</CardContent>
|
|
</Card>
|
|
|
|
<Card className="shadow-none border-border overflow-hidden">
|
|
<CardHeader>
|
|
<CardTitle className="text-base font-semibold">Run Transcript (compact density)</CardTitle>
|
|
<p className="text-xs text-muted-foreground">
|
|
Same parsed events, compact density — matches the live-run widget on the issue thread.
|
|
</p>
|
|
</CardHeader>
|
|
<CardContent>
|
|
<RunTranscriptView entries={entries} mode="nice" density="compact" streaming={false} />
|
|
</CardContent>
|
|
</Card>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
const SKILLS_COMPANY_ID = "company-storybook";
|
|
|
|
const defaultStoreSkillFields = {
|
|
iconUrl: null,
|
|
color: null,
|
|
tagline: null,
|
|
authorName: null,
|
|
homepageUrl: null,
|
|
categories: [],
|
|
sharingScope: "company" as const,
|
|
publicShareToken: null,
|
|
forkedFromSkillId: null,
|
|
forkedFromCompanyId: null,
|
|
starCount: 0,
|
|
installCount: 1,
|
|
forkCount: 0,
|
|
currentVersionId: null,
|
|
};
|
|
|
|
const acpxSkillsCompanyLibrary: CompanySkillListItem[] = [
|
|
{
|
|
id: "skill-paperclip",
|
|
companyId: SKILLS_COMPANY_ID,
|
|
key: "paperclip",
|
|
slug: "paperclip",
|
|
name: "Paperclip",
|
|
description:
|
|
"Coordination skill: heartbeats, checkout, comments, and routine API patterns for Paperclip agents.",
|
|
sourceType: "local_path",
|
|
sourceLocator: "skills/paperclip",
|
|
sourceRef: null,
|
|
trustLevel: "scripts_executables",
|
|
compatibility: "compatible",
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
|
|
...defaultStoreSkillFields,
|
|
createdAt: new Date("2026-04-12T09:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-22T15:30:00.000Z"),
|
|
attachedAgentCount: 4,
|
|
editable: false,
|
|
editableReason: "Required by Paperclip",
|
|
sourceLabel: "Paperclip",
|
|
sourceBadge: "paperclip",
|
|
sourcePath: "skills/paperclip",
|
|
catalogKind: null,
|
|
originHash: null,
|
|
packageName: null,
|
|
packageVersion: null,
|
|
},
|
|
{
|
|
id: "skill-design-guide",
|
|
companyId: SKILLS_COMPANY_ID,
|
|
key: "design-guide",
|
|
slug: "design-guide",
|
|
name: "Design guide",
|
|
description:
|
|
"Paperclip UI design system reference: tokens, typography, status colors, and reusable component patterns.",
|
|
sourceType: "local_path",
|
|
sourceLocator: "skills/design-guide",
|
|
sourceRef: null,
|
|
trustLevel: "markdown_only",
|
|
compatibility: "compatible",
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
|
|
...defaultStoreSkillFields,
|
|
createdAt: new Date("2026-04-15T10:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-25T12:00:00.000Z"),
|
|
attachedAgentCount: 2,
|
|
editable: true,
|
|
editableReason: null,
|
|
sourceLabel: "Local",
|
|
sourceBadge: "local",
|
|
sourcePath: "skills/design-guide",
|
|
catalogKind: null,
|
|
originHash: null,
|
|
packageName: null,
|
|
packageVersion: null,
|
|
},
|
|
{
|
|
id: "skill-mobile-qa",
|
|
companyId: SKILLS_COMPANY_ID,
|
|
key: "mobile-app-qa",
|
|
slug: "mobile-app-qa",
|
|
name: "Mobile app QA",
|
|
description:
|
|
"Exploratory QA flows for mobile/web apps using Chrome automation. Captures bugs and writes a final report.",
|
|
sourceType: "local_path",
|
|
sourceLocator: "skills/mobile-app-qa",
|
|
sourceRef: null,
|
|
trustLevel: "assets",
|
|
compatibility: "compatible",
|
|
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
|
|
...defaultStoreSkillFields,
|
|
createdAt: new Date("2026-04-18T11:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-26T09:30:00.000Z"),
|
|
attachedAgentCount: 1,
|
|
editable: true,
|
|
editableReason: null,
|
|
sourceLabel: "Local",
|
|
sourceBadge: "local",
|
|
sourcePath: "skills/mobile-app-qa",
|
|
catalogKind: null,
|
|
originHash: null,
|
|
packageName: null,
|
|
packageVersion: null,
|
|
},
|
|
];
|
|
|
|
function buildAcpxAgent({
|
|
agentId,
|
|
acpAgent,
|
|
desiredSkills,
|
|
}: {
|
|
agentId: string;
|
|
acpAgent: "claude" | "codex" | "custom";
|
|
desiredSkills: string[];
|
|
}): Agent {
|
|
return {
|
|
id: agentId,
|
|
companyId: SKILLS_COMPANY_ID,
|
|
name: `ACPX ${acpAgent === "custom" ? "Custom" : acpAgent === "codex" ? "Codex" : "Claude"}`,
|
|
urlKey: `acpx-${acpAgent}`,
|
|
role: "engineer",
|
|
title: `ACPX ${acpAgent} agent`,
|
|
icon: "code",
|
|
status: "idle",
|
|
reportsTo: null,
|
|
capabilities: "Routes work through the ACPX adapter for skill-tagged agent flows.",
|
|
adapterType: "acpx_local",
|
|
adapterConfig: {
|
|
agent: acpAgent,
|
|
mode: "persistent",
|
|
permissionMode: "approve-all",
|
|
paperclipSkillSync: {
|
|
desiredSkills,
|
|
},
|
|
},
|
|
runtimeConfig: {},
|
|
budgetMonthlyCents: 100_000,
|
|
spentMonthlyCents: 0,
|
|
pauseReason: null,
|
|
pausedAt: null,
|
|
permissions: { canCreateAgents: false },
|
|
lastHeartbeatAt: null,
|
|
metadata: null,
|
|
createdAt: new Date("2026-04-30T12:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-30T12:00:00.000Z"),
|
|
} as Agent;
|
|
}
|
|
|
|
function buildAcpxClaudeSnapshot(): AgentSkillSnapshot {
|
|
return {
|
|
adapterType: "acpx_local",
|
|
supported: true,
|
|
mode: "ephemeral",
|
|
desiredSkills: ["paperclip", "design-guide"],
|
|
warnings: [],
|
|
entries: [
|
|
{
|
|
key: "paperclip",
|
|
runtimeName: "paperclip",
|
|
desired: true,
|
|
managed: true,
|
|
state: "configured",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/paperclip",
|
|
targetPath: null,
|
|
detail: "Will be mounted into the next ACPX Claude session.",
|
|
},
|
|
{
|
|
key: "design-guide",
|
|
runtimeName: "design-guide",
|
|
desired: true,
|
|
managed: true,
|
|
state: "configured",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/design-guide",
|
|
targetPath: null,
|
|
detail: "Will be mounted into the next ACPX Claude session.",
|
|
},
|
|
{
|
|
key: "mobile-app-qa",
|
|
runtimeName: "mobile-app-qa",
|
|
desired: false,
|
|
managed: true,
|
|
state: "available",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/mobile-app-qa",
|
|
targetPath: null,
|
|
detail: null,
|
|
},
|
|
],
|
|
};
|
|
}
|
|
|
|
function buildAcpxCodexSnapshot(): AgentSkillSnapshot {
|
|
return {
|
|
adapterType: "acpx_local",
|
|
supported: true,
|
|
mode: "ephemeral",
|
|
desiredSkills: ["paperclip"],
|
|
warnings: [],
|
|
entries: [
|
|
{
|
|
key: "paperclip",
|
|
runtimeName: "paperclip",
|
|
desired: true,
|
|
managed: true,
|
|
state: "configured",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/paperclip",
|
|
targetPath: null,
|
|
detail: "Will be linked into the effective CODEX_HOME/skills/ directory for the next ACPX Codex session.",
|
|
},
|
|
{
|
|
key: "design-guide",
|
|
runtimeName: "design-guide",
|
|
desired: false,
|
|
managed: true,
|
|
state: "available",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/design-guide",
|
|
targetPath: null,
|
|
detail: null,
|
|
},
|
|
{
|
|
key: "mobile-app-qa",
|
|
runtimeName: "mobile-app-qa",
|
|
desired: false,
|
|
managed: true,
|
|
state: "available",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/mobile-app-qa",
|
|
targetPath: null,
|
|
detail: null,
|
|
},
|
|
],
|
|
};
|
|
}
|
|
|
|
function buildAcpxCustomSnapshot(): AgentSkillSnapshot {
|
|
return {
|
|
adapterType: "acpx_local",
|
|
supported: false,
|
|
mode: "unsupported",
|
|
desiredSkills: ["design-guide"],
|
|
warnings: [
|
|
"Custom ACP commands do not expose a Paperclip skill integration contract yet; selected skills are tracked only.",
|
|
],
|
|
entries: [
|
|
{
|
|
key: "paperclip",
|
|
runtimeName: "paperclip",
|
|
desired: false,
|
|
managed: true,
|
|
state: "available",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/paperclip",
|
|
targetPath: null,
|
|
detail: null,
|
|
},
|
|
{
|
|
key: "design-guide",
|
|
runtimeName: "design-guide",
|
|
desired: true,
|
|
managed: true,
|
|
state: "configured",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/design-guide",
|
|
targetPath: null,
|
|
detail:
|
|
"Desired state is stored in Paperclip only; custom ACP commands need an explicit skill integration contract before runtime sync is available.",
|
|
},
|
|
{
|
|
key: "mobile-app-qa",
|
|
runtimeName: "mobile-app-qa",
|
|
desired: false,
|
|
managed: true,
|
|
state: "available",
|
|
origin: "company_managed",
|
|
originLabel: "Managed by Paperclip",
|
|
readOnly: false,
|
|
sourcePath: "skills/mobile-app-qa",
|
|
targetPath: null,
|
|
detail: null,
|
|
},
|
|
],
|
|
};
|
|
}
|
|
|
|
function StoryFrame({
|
|
title,
|
|
subtitle,
|
|
children,
|
|
}: {
|
|
title: string;
|
|
subtitle: string;
|
|
children: ReactNode;
|
|
}) {
|
|
return (
|
|
<div className="mx-auto max-w-3xl space-y-5 p-6">
|
|
<header className="space-y-2">
|
|
<Badge variant="outline" className="rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.18em]">
|
|
UX preview
|
|
</Badge>
|
|
<h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
|
|
<p className="text-sm text-muted-foreground">{subtitle}</p>
|
|
</header>
|
|
|
|
<Card className="shadow-none border-border">
|
|
<CardHeader>
|
|
<CardTitle className="text-base font-semibold">Agent detail — Skills tab</CardTitle>
|
|
</CardHeader>
|
|
<CardContent>{children}</CardContent>
|
|
</Card>
|
|
</div>
|
|
);
|
|
}
|
|
|
|
function AcpxSkillsState({
|
|
agent,
|
|
snapshot,
|
|
library,
|
|
}: {
|
|
agent: Agent;
|
|
snapshot: AgentSkillSnapshot;
|
|
library: CompanySkillListItem[];
|
|
}) {
|
|
const queryClient = useQueryClient();
|
|
queryClient.setQueryData(queryKeys.companySkills.list(SKILLS_COMPANY_ID), library);
|
|
queryClient.setQueryData(queryKeys.agents.skills(agent.id), snapshot);
|
|
return <AgentSkillsTab agent={agent} companyId={SKILLS_COMPANY_ID} />;
|
|
}
|
|
|
|
function AcpxClaudeSkillsStory() {
|
|
const agent = buildAcpxAgent({
|
|
agentId: "agent-acpx-claude",
|
|
acpAgent: "claude",
|
|
desiredSkills: ["paperclip", "design-guide"],
|
|
});
|
|
return (
|
|
<StoryFrame
|
|
title="ACPX Claude — Skills tab"
|
|
subtitle="Runtime-synced state. Selected skills are mounted into the next ACPX Claude session via the Paperclip skills directory."
|
|
>
|
|
<AcpxSkillsState agent={agent} snapshot={buildAcpxClaudeSnapshot()} library={acpxSkillsCompanyLibrary} />
|
|
</StoryFrame>
|
|
);
|
|
}
|
|
|
|
function AcpxCodexSkillsStory() {
|
|
const agent = buildAcpxAgent({
|
|
agentId: "agent-acpx-codex",
|
|
acpAgent: "codex",
|
|
desiredSkills: ["paperclip"],
|
|
});
|
|
return (
|
|
<StoryFrame
|
|
title="ACPX Codex — Skills tab"
|
|
subtitle="Runtime-synced state. Selected skills are linked into the effective CODEX_HOME/skills/ directory for the next ACPX Codex session."
|
|
>
|
|
<AcpxSkillsState agent={agent} snapshot={buildAcpxCodexSnapshot()} library={acpxSkillsCompanyLibrary} />
|
|
</StoryFrame>
|
|
);
|
|
}
|
|
|
|
function AcpxCustomSkillsStory() {
|
|
const agent = buildAcpxAgent({
|
|
agentId: "agent-acpx-custom",
|
|
acpAgent: "custom",
|
|
desiredSkills: ["design-guide"],
|
|
});
|
|
return (
|
|
<StoryFrame
|
|
title="ACPX custom — Skills tab"
|
|
subtitle="Unsupported runtime sync. Desired skills are tracked in Paperclip only until a custom ACP command declares a skill integration contract."
|
|
>
|
|
<AcpxSkillsState agent={agent} snapshot={buildAcpxCustomSnapshot()} library={acpxSkillsCompanyLibrary} />
|
|
</StoryFrame>
|
|
);
|
|
}
|
|
|
|
function AcpxClaudeSkillsLoadingStory() {
|
|
const agent = buildAcpxAgent({
|
|
agentId: "agent-acpx-claude-loading",
|
|
acpAgent: "claude",
|
|
desiredSkills: [],
|
|
});
|
|
return (
|
|
<StoryFrame
|
|
title="ACPX Claude — Skills tab (loading)"
|
|
subtitle="Initial render before /api/agents/{id}/skills resolves. Uses the shared list skeleton."
|
|
>
|
|
<AgentSkillsTab agent={agent} companyId={SKILLS_COMPANY_ID} />
|
|
</StoryFrame>
|
|
);
|
|
}
|
|
|
|
function AcpxClaudeSkillsEmptyLibraryStory() {
|
|
const agent = buildAcpxAgent({
|
|
agentId: "agent-acpx-claude-empty",
|
|
acpAgent: "claude",
|
|
desiredSkills: [],
|
|
});
|
|
const emptySnapshot: AgentSkillSnapshot = {
|
|
adapterType: "acpx_local",
|
|
supported: true,
|
|
mode: "ephemeral",
|
|
desiredSkills: [],
|
|
warnings: [],
|
|
entries: [],
|
|
};
|
|
return (
|
|
<StoryFrame
|
|
title="ACPX Claude — Skills tab (empty company library)"
|
|
subtitle="Runtime supports skills, but the company library has no skills imported yet. Operator is prompted to import skills first."
|
|
>
|
|
<AcpxSkillsState agent={agent} snapshot={emptySnapshot} library={[]} />
|
|
</StoryFrame>
|
|
);
|
|
}
|
|
|
|
const meta: Meta = {
|
|
title: "Adapters / acpx_local",
|
|
parameters: {
|
|
layout: "fullscreen",
|
|
},
|
|
};
|
|
|
|
export default meta;
|
|
|
|
export const ConfigForm: StoryObj = {
|
|
name: "Agent config form",
|
|
render: () => <AcpxLocalConfigStory />,
|
|
};
|
|
|
|
export const Transcript: StoryObj = {
|
|
name: "Streamed run transcript",
|
|
render: () => <AcpxLocalTranscriptStory />,
|
|
};
|
|
|
|
export const SkillsTabClaude: StoryObj = {
|
|
name: "Skills tab — ACPX Claude",
|
|
render: () => <AcpxClaudeSkillsStory />,
|
|
};
|
|
|
|
export const SkillsTabCodex: StoryObj = {
|
|
name: "Skills tab — ACPX Codex",
|
|
render: () => <AcpxCodexSkillsStory />,
|
|
};
|
|
|
|
export const SkillsTabCustom: StoryObj = {
|
|
name: "Skills tab — ACPX custom (unsupported)",
|
|
render: () => <AcpxCustomSkillsStory />,
|
|
};
|
|
|
|
export const SkillsTabLoading: StoryObj = {
|
|
name: "Skills tab — loading",
|
|
render: () => <AcpxClaudeSkillsLoadingStory />,
|
|
};
|
|
|
|
export const SkillsTabEmptyLibrary: StoryObj = {
|
|
name: "Skills tab — empty company library",
|
|
render: () => <AcpxClaudeSkillsEmptyLibraryStory />,
|
|
};
|