merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/ui/src/adapters/claude-local/config-fields.tsx

@@ -0,0 +1,138 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  ToggleField,
+  DraftInput,
+  DraftNumberInput,
+  help,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+import { LocalWorkspaceRuntimeFields } from "../local-workspace-runtime-fields";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
+
+export function ClaudeLocalConfigFields({
+  mode,
+  isCreate,
+  adapterType,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  models,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  return (
+    <>
+      {!hideInstructionsFile && (
+        <Field label="Agent instructions file" hint={instructionsFileHint}>
+          <div className="flex items-center gap-2">
+            <DraftInput
+              value={
+                isCreate
+                  ? values!.instructionsFilePath ?? ""
+                  : eff(
+                      "adapterConfig",
+                      "instructionsFilePath",
+                      String(config.instructionsFilePath ?? ""),
+                    )
+              }
+              onCommit={(v) =>
+                isCreate
+                  ? set!({ instructionsFilePath: v })
+                  : mark("adapterConfig", "instructionsFilePath", v || undefined)
+              }
+              immediate
+              className={inputClass}
+              placeholder="/absolute/path/to/AGENTS.md"
+            />
+            <ChoosePathButton />
+          </div>
+        </Field>
+      )}
+      <LocalWorkspaceRuntimeFields
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+        eff={eff}
+        mode={mode}
+        adapterType={adapterType}
+        models={models}
+      />
+    </>
+  );
+}
+
+export function ClaudeLocalAdvancedFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+}: AdapterConfigFieldsProps) {
+  return (
+    <>
+      <ToggleField
+        label="Enable Chrome"
+        hint={help.chrome}
+        checked={
+          isCreate
+            ? values!.chrome
+            : eff("adapterConfig", "chrome", config.chrome === true)
+        }
+        onChange={(v) =>
+          isCreate
+            ? set!({ chrome: v })
+            : mark("adapterConfig", "chrome", v)
+        }
+      />
+      <ToggleField
+        label="Skip permissions"
+        hint={help.dangerouslySkipPermissions}
+        checked={
+          isCreate
+            ? values!.dangerouslySkipPermissions
+            : eff(
+                "adapterConfig",
+                "dangerouslySkipPermissions",
+                config.dangerouslySkipPermissions !== false,
+              )
+        }
+        onChange={(v) =>
+          isCreate
+            ? set!({ dangerouslySkipPermissions: v })
+            : mark("adapterConfig", "dangerouslySkipPermissions", v)
+        }
+      />
+      <Field label="Max turns per run" hint={help.maxTurnsPerRun}>
+        {isCreate ? (
+          <input
+            type="number"
+            className={inputClass}
+            value={values!.maxTurnsPerRun}
+            onChange={(e) => set!({ maxTurnsPerRun: Number(e.target.value) })}
+          />
+        ) : (
+          <DraftNumberInput
+            value={eff(
+              "adapterConfig",
+              "maxTurnsPerRun",
+              Number(config.maxTurnsPerRun ?? 300),
+            )}
+            onCommit={(v) => mark("adapterConfig", "maxTurnsPerRun", v || 300)}
+            immediate
+            className={inputClass}
+          />
+        )}
+      </Field>
+    </>
+  );
+}

paperclip-reference/ui/src/adapters/claude-local/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseClaudeStdoutLine } from "@paperclipai/adapter-claude-local/ui";
+import { ClaudeLocalConfigFields } from "./config-fields";
+import { buildClaudeLocalConfig } from "@paperclipai/adapter-claude-local/ui";
+
+export const claudeLocalUIAdapter: UIAdapterModule = {
+  type: "claude_local",
+  label: "Claude Code (local)",
+  parseStdoutLine: parseClaudeStdoutLine,
+  ConfigFields: ClaudeLocalConfigFields,
+  buildAdapterConfig: buildClaudeLocalConfig,
+};

paperclip-reference/ui/src/adapters/codex-local/config-fields.tsx

@@ -0,0 +1,104 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  ToggleField,
+  DraftInput,
+  help,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+import { LocalWorkspaceRuntimeFields } from "../local-workspace-runtime-fields";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime. Note: Codex may still auto-apply repo-scoped AGENTS.md files from the workspace.";
+
+export function CodexLocalConfigFields({
+  mode,
+  isCreate,
+  adapterType,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  models,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  const bypassEnabled =
+    config.dangerouslyBypassApprovalsAndSandbox === true || config.dangerouslyBypassSandbox === true;
+
+  return (
+    <>
+      {!hideInstructionsFile && (
+        <Field label="Agent instructions file" hint={instructionsFileHint}>
+          <div className="flex items-center gap-2">
+            <DraftInput
+              value={
+                isCreate
+                  ? values!.instructionsFilePath ?? ""
+                  : eff(
+                      "adapterConfig",
+                      "instructionsFilePath",
+                      String(config.instructionsFilePath ?? ""),
+                    )
+              }
+              onCommit={(v) =>
+                isCreate
+                  ? set!({ instructionsFilePath: v })
+                  : mark("adapterConfig", "instructionsFilePath", v || undefined)
+              }
+              immediate
+              className={inputClass}
+              placeholder="/absolute/path/to/AGENTS.md"
+            />
+            <ChoosePathButton />
+          </div>
+        </Field>
+      )}
+      <ToggleField
+        label="Bypass sandbox"
+        hint={help.dangerouslyBypassSandbox}
+        checked={
+          isCreate
+            ? values!.dangerouslyBypassSandbox
+            : eff(
+                "adapterConfig",
+                "dangerouslyBypassApprovalsAndSandbox",
+                bypassEnabled,
+              )
+        }
+        onChange={(v) =>
+          isCreate
+            ? set!({ dangerouslyBypassSandbox: v })
+            : mark("adapterConfig", "dangerouslyBypassApprovalsAndSandbox", v)
+        }
+      />
+      <ToggleField
+        label="Enable search"
+        hint={help.search}
+        checked={
+          isCreate
+            ? values!.search
+            : eff("adapterConfig", "search", !!config.search)
+        }
+        onChange={(v) =>
+          isCreate
+            ? set!({ search: v })
+            : mark("adapterConfig", "search", v)
+        }
+      />
+      <LocalWorkspaceRuntimeFields
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+        eff={eff}
+        mode={mode}
+        adapterType={adapterType}
+        models={models}
+      />
+    </>
+  );
+}

paperclip-reference/ui/src/adapters/codex-local/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseCodexStdoutLine } from "@paperclipai/adapter-codex-local/ui";
+import { CodexLocalConfigFields } from "./config-fields";
+import { buildCodexLocalConfig } from "@paperclipai/adapter-codex-local/ui";
+
+export const codexLocalUIAdapter: UIAdapterModule = {
+  type: "codex_local",
+  label: "Codex (local)",
+  parseStdoutLine: parseCodexStdoutLine,
+  ConfigFields: CodexLocalConfigFields,
+  buildAdapterConfig: buildCodexLocalConfig,
+};

paperclip-reference/ui/src/adapters/cursor/config-fields.tsx

@@ -0,0 +1,49 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the prompt at runtime.";
+
+export function CursorLocalConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  if (hideInstructionsFile) return null;
+  return (
+    <Field label="Agent instructions file" hint={instructionsFileHint}>
+      <div className="flex items-center gap-2">
+        <DraftInput
+          value={
+            isCreate
+              ? values!.instructionsFilePath ?? ""
+              : eff(
+                  "adapterConfig",
+                  "instructionsFilePath",
+                  String(config.instructionsFilePath ?? ""),
+                )
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ instructionsFilePath: v })
+              : mark("adapterConfig", "instructionsFilePath", v || undefined)
+          }
+          immediate
+          className={inputClass}
+          placeholder="/absolute/path/to/AGENTS.md"
+        />
+        <ChoosePathButton />
+      </div>
+    </Field>
+  );
+}

paperclip-reference/ui/src/adapters/cursor/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseCursorStdoutLine } from "@paperclipai/adapter-cursor-local/ui";
+import { CursorLocalConfigFields } from "./config-fields";
+import { buildCursorLocalConfig } from "@paperclipai/adapter-cursor-local/ui";
+
+export const cursorLocalUIAdapter: UIAdapterModule = {
+  type: "cursor",
+  label: "Cursor CLI (local)",
+  parseStdoutLine: parseCursorStdoutLine,
+  ConfigFields: CursorLocalConfigFields,
+  buildAdapterConfig: buildCursorLocalConfig,
+};

paperclip-reference/ui/src/adapters/gemini-local/config-fields.tsx

@@ -0,0 +1,51 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  DraftInput,
+  Field,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Prepended to the Gemini prompt at runtime.";
+
+export function GeminiLocalConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  if (hideInstructionsFile) return null;
+  return (
+    <>
+      <Field label="Agent instructions file" hint={instructionsFileHint}>
+        <div className="flex items-center gap-2">
+          <DraftInput
+            value={
+              isCreate
+                ? values!.instructionsFilePath ?? ""
+                : eff(
+                    "adapterConfig",
+                    "instructionsFilePath",
+                    String(config.instructionsFilePath ?? ""),
+                  )
+            }
+            onCommit={(v) =>
+              isCreate
+                ? set!({ instructionsFilePath: v })
+                : mark("adapterConfig", "instructionsFilePath", v || undefined)
+            }
+            immediate
+            className={inputClass}
+            placeholder="/absolute/path/to/AGENTS.md"
+          />
+          <ChoosePathButton />
+        </div>
+      </Field>
+    </>
+  );
+}

paperclip-reference/ui/src/adapters/gemini-local/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseGeminiStdoutLine } from "@paperclipai/adapter-gemini-local/ui";
+import { GeminiLocalConfigFields } from "./config-fields";
+import { buildGeminiLocalConfig } from "@paperclipai/adapter-gemini-local/ui";
+
+export const geminiLocalUIAdapter: UIAdapterModule = {
+  type: "gemini_local",
+  label: "Gemini CLI (local)",
+  parseStdoutLine: parseGeminiStdoutLine,
+  ConfigFields: GeminiLocalConfigFields,
+  buildAdapterConfig: buildGeminiLocalConfig,
+};

paperclip-reference/ui/src/adapters/http/build-config.ts

@@ -0,0 +1,9 @@
+import type { CreateConfigValues } from "../../components/AgentConfigForm";
+
+export function buildHttpConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.url) ac.url = v.url;
+  ac.method = "POST";
+  ac.timeoutMs = 15000;
+  return ac;
+}

paperclip-reference/ui/src/adapters/http/config-fields.tsx

@@ -0,0 +1,38 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+  help,
+} from "../../components/agent-config-primitives";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+
+export function HttpConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+}: AdapterConfigFieldsProps) {
+  return (
+    <Field label="Webhook URL" hint={help.webhookUrl}>
+      <DraftInput
+        value={
+          isCreate
+            ? values!.url
+            : eff("adapterConfig", "url", String(config.url ?? ""))
+        }
+        onCommit={(v) =>
+          isCreate
+            ? set!({ url: v })
+            : mark("adapterConfig", "url", v || undefined)
+        }
+        immediate
+        className={inputClass}
+        placeholder="https://..."
+      />
+    </Field>
+  );
+}

paperclip-reference/ui/src/adapters/http/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseHttpStdoutLine } from "./parse-stdout";
+import { HttpConfigFields } from "./config-fields";
+import { buildHttpConfig } from "./build-config";
+
+export const httpUIAdapter: UIAdapterModule = {
+  type: "http",
+  label: "HTTP Webhook",
+  parseStdoutLine: parseHttpStdoutLine,
+  ConfigFields: HttpConfigFields,
+  buildAdapterConfig: buildHttpConfig,
+};

paperclip-reference/ui/src/adapters/http/parse-stdout.ts

@@ -0,0 +1,5 @@
+import type { TranscriptEntry } from "../types";
+
+export function parseHttpStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  return [{ kind: "stdout", ts, text: line }];
+}

paperclip-reference/ui/src/adapters/index.ts

@@ -0,0 +1,9 @@
+export { getUIAdapter, listUIAdapters } from "./registry";
+export { buildTranscript } from "./transcript";
+export type {
+  TranscriptEntry,
+  StdoutLineParser,
+  UIAdapterModule,
+  AdapterConfigFieldsProps,
+} from "./types";
+export type { RunLogChunk } from "./transcript";

paperclip-reference/ui/src/adapters/local-workspace-runtime-fields.tsx

@@ -0,0 +1,5 @@
+import type { AdapterConfigFieldsProps } from "./types";
+
+export function LocalWorkspaceRuntimeFields(_props: AdapterConfigFieldsProps) {
+  return null;
+}

paperclip-reference/ui/src/adapters/openclaw-gateway/config-fields.tsx

@@ -0,0 +1,237 @@
+import { useState } from "react";
+import { Eye, EyeOff } from "lucide-react";
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+  help,
+} from "../../components/agent-config-primitives";
+import {
+  PayloadTemplateJsonField,
+  RuntimeServicesJsonField,
+} from "../runtime-json-fields";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+
+function SecretField({
+  label,
+  value,
+  onCommit,
+  placeholder,
+}: {
+  label: string;
+  value: string;
+  onCommit: (v: string) => void;
+  placeholder?: string;
+}) {
+  const [visible, setVisible] = useState(false);
+  return (
+    <Field label={label}>
+      <div className="relative">
+        <button
+          type="button"
+          onClick={() => setVisible((v) => !v)}
+          className="absolute left-2 top-1/2 -translate-y-1/2 text-muted-foreground/50 hover:text-muted-foreground transition-colors"
+        >
+          {visible ? <Eye className="h-3.5 w-3.5" /> : <EyeOff className="h-3.5 w-3.5" />}
+        </button>
+        <DraftInput
+          value={value}
+          onCommit={onCommit}
+          immediate
+          type={visible ? "text" : "password"}
+          className={inputClass + " pl-8"}
+          placeholder={placeholder}
+        />
+      </div>
+    </Field>
+  );
+}
+
+function parseScopes(value: unknown): string {
+  if (Array.isArray(value)) {
+    return value.filter((entry): entry is string => typeof entry === "string").join(", ");
+  }
+  return typeof value === "string" ? value : "";
+}
+
+export function OpenClawGatewayConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+}: AdapterConfigFieldsProps) {
+  const configuredHeaders =
+    config.headers && typeof config.headers === "object" && !Array.isArray(config.headers)
+      ? (config.headers as Record<string, unknown>)
+      : {};
+  const effectiveHeaders =
+    (eff("adapterConfig", "headers", configuredHeaders) as Record<string, unknown>) ?? {};
+
+  const effectiveGatewayToken = typeof effectiveHeaders["x-openclaw-token"] === "string"
+    ? String(effectiveHeaders["x-openclaw-token"])
+    : typeof effectiveHeaders["x-openclaw-auth"] === "string"
+      ? String(effectiveHeaders["x-openclaw-auth"])
+      : "";
+
+  const commitGatewayToken = (rawValue: string) => {
+    const nextValue = rawValue.trim();
+    const nextHeaders: Record<string, unknown> = { ...effectiveHeaders };
+    if (nextValue) {
+      nextHeaders["x-openclaw-token"] = nextValue;
+      delete nextHeaders["x-openclaw-auth"];
+    } else {
+      delete nextHeaders["x-openclaw-token"];
+      delete nextHeaders["x-openclaw-auth"];
+    }
+    mark("adapterConfig", "headers", Object.keys(nextHeaders).length > 0 ? nextHeaders : undefined);
+  };
+
+  const sessionStrategy = eff(
+    "adapterConfig",
+    "sessionKeyStrategy",
+    String(config.sessionKeyStrategy ?? "fixed"),
+  );
+
+  return (
+    <>
+      <Field label="Gateway URL" hint={help.webhookUrl}>
+        <DraftInput
+          value={
+            isCreate
+              ? values!.url
+              : eff("adapterConfig", "url", String(config.url ?? ""))
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ url: v })
+              : mark("adapterConfig", "url", v || undefined)
+          }
+          immediate
+          className={inputClass}
+          placeholder="ws://127.0.0.1:18789"
+        />
+      </Field>
+
+      <PayloadTemplateJsonField
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+      />
+
+      <RuntimeServicesJsonField
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+      />
+
+      {!isCreate && (
+        <>
+          <Field label="Paperclip API URL override">
+            <DraftInput
+              value={
+                eff(
+                  "adapterConfig",
+                  "paperclipApiUrl",
+                  String(config.paperclipApiUrl ?? ""),
+                )
+              }
+              onCommit={(v) => mark("adapterConfig", "paperclipApiUrl", v || undefined)}
+              immediate
+              className={inputClass}
+              placeholder="https://paperclip.example"
+            />
+          </Field>
+
+          <Field label="Session strategy">
+            <select
+              value={sessionStrategy}
+              onChange={(e) => mark("adapterConfig", "sessionKeyStrategy", e.target.value)}
+              className={inputClass}
+            >
+              <option value="fixed">Fixed</option>
+              <option value="issue">Per issue</option>
+              <option value="run">Per run</option>
+            </select>
+          </Field>
+
+          {sessionStrategy === "fixed" && (
+            <Field label="Session key">
+              <DraftInput
+                value={eff("adapterConfig", "sessionKey", String(config.sessionKey ?? "paperclip"))}
+                onCommit={(v) => mark("adapterConfig", "sessionKey", v || undefined)}
+                immediate
+                className={inputClass}
+                placeholder="paperclip"
+              />
+            </Field>
+          )}
+
+          <SecretField
+            label="Gateway auth token (x-openclaw-token)"
+            value={effectiveGatewayToken}
+            onCommit={commitGatewayToken}
+            placeholder="OpenClaw gateway token"
+          />
+
+          <Field label="Role">
+            <DraftInput
+              value={eff("adapterConfig", "role", String(config.role ?? "operator"))}
+              onCommit={(v) => mark("adapterConfig", "role", v || undefined)}
+              immediate
+              className={inputClass}
+              placeholder="operator"
+            />
+          </Field>
+
+          <Field label="Scopes (comma-separated)">
+            <DraftInput
+              value={eff("adapterConfig", "scopes", parseScopes(config.scopes ?? ["operator.admin"]))}
+              onCommit={(v) => {
+                const parsed = v
+                  .split(",")
+                  .map((entry) => entry.trim())
+                  .filter(Boolean);
+                mark("adapterConfig", "scopes", parsed.length > 0 ? parsed : undefined);
+              }}
+              immediate
+              className={inputClass}
+              placeholder="operator.admin"
+            />
+          </Field>
+
+          <Field label="Wait timeout (ms)">
+            <DraftInput
+              value={eff("adapterConfig", "waitTimeoutMs", String(config.waitTimeoutMs ?? "120000"))}
+              onCommit={(v) => {
+                const parsed = Number.parseInt(v.trim(), 10);
+                mark(
+                  "adapterConfig",
+                  "waitTimeoutMs",
+                  Number.isFinite(parsed) && parsed > 0 ? parsed : undefined,
+                );
+              }}
+              immediate
+              className={inputClass}
+              placeholder="120000"
+            />
+          </Field>
+
+          <Field label="Device auth">
+            <div className="text-xs text-muted-foreground leading-relaxed">
+              Always enabled for gateway agents. Paperclip persists a device key during onboarding so pairing approvals
+              remain stable across runs.
+            </div>
+          </Field>
+        </>
+      )}
+    </>
+  );
+}

paperclip-reference/ui/src/adapters/openclaw-gateway/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseOpenClawGatewayStdoutLine } from "@paperclipai/adapter-openclaw-gateway/ui";
+import { buildOpenClawGatewayConfig } from "@paperclipai/adapter-openclaw-gateway/ui";
+import { OpenClawGatewayConfigFields } from "./config-fields";
+
+export const openClawGatewayUIAdapter: UIAdapterModule = {
+  type: "openclaw_gateway",
+  label: "OpenClaw Gateway",
+  parseStdoutLine: parseOpenClawGatewayStdoutLine,
+  ConfigFields: OpenClawGatewayConfigFields,
+  buildAdapterConfig: buildOpenClawGatewayConfig,
+};

paperclip-reference/ui/src/adapters/opencode-local/config-fields.tsx

@@ -0,0 +1,49 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
+
+export function OpenCodeLocalConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  if (hideInstructionsFile) return null;
+  return (
+    <Field label="Agent instructions file" hint={instructionsFileHint}>
+      <div className="flex items-center gap-2">
+        <DraftInput
+          value={
+            isCreate
+              ? values!.instructionsFilePath ?? ""
+              : eff(
+                  "adapterConfig",
+                  "instructionsFilePath",
+                  String(config.instructionsFilePath ?? ""),
+                )
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ instructionsFilePath: v })
+              : mark("adapterConfig", "instructionsFilePath", v || undefined)
+          }
+          immediate
+          className={inputClass}
+          placeholder="/absolute/path/to/AGENTS.md"
+        />
+        <ChoosePathButton />
+      </div>
+    </Field>
+  );
+}

paperclip-reference/ui/src/adapters/opencode-local/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseOpenCodeStdoutLine } from "@paperclipai/adapter-opencode-local/ui";
+import { OpenCodeLocalConfigFields } from "./config-fields";
+import { buildOpenCodeLocalConfig } from "@paperclipai/adapter-opencode-local/ui";
+
+export const openCodeLocalUIAdapter: UIAdapterModule = {
+  type: "opencode_local",
+  label: "OpenCode (local)",
+  parseStdoutLine: parseOpenCodeStdoutLine,
+  ConfigFields: OpenCodeLocalConfigFields,
+  buildAdapterConfig: buildOpenCodeLocalConfig,
+};

paperclip-reference/ui/src/adapters/pi-local/config-fields.tsx

@@ -0,0 +1,49 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+} from "../../components/agent-config-primitives";
+import { ChoosePathButton } from "../../components/PathInstructionsModal";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+const instructionsFileHint =
+  "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";
+
+export function PiLocalConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+  hideInstructionsFile,
+}: AdapterConfigFieldsProps) {
+  if (hideInstructionsFile) return null;
+  return (
+    <Field label="Agent instructions file" hint={instructionsFileHint}>
+      <div className="flex items-center gap-2">
+        <DraftInput
+          value={
+            isCreate
+              ? values!.instructionsFilePath ?? ""
+              : eff(
+                  "adapterConfig",
+                  "instructionsFilePath",
+                  String(config.instructionsFilePath ?? ""),
+                )
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ instructionsFilePath: v })
+              : mark("adapterConfig", "instructionsFilePath", v || undefined)
+          }
+          immediate
+          className={inputClass}
+          placeholder="/absolute/path/to/AGENTS.md"
+        />
+        <ChoosePathButton />
+      </div>
+    </Field>
+  );
+}

paperclip-reference/ui/src/adapters/pi-local/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parsePiStdoutLine } from "@paperclipai/adapter-pi-local/ui";
+import { PiLocalConfigFields } from "./config-fields";
+import { buildPiLocalConfig } from "@paperclipai/adapter-pi-local/ui";
+
+export const piLocalUIAdapter: UIAdapterModule = {
+  type: "pi_local",
+  label: "Pi (local)",
+  parseStdoutLine: parsePiStdoutLine,
+  ConfigFields: PiLocalConfigFields,
+  buildAdapterConfig: buildPiLocalConfig,
+};

paperclip-reference/ui/src/adapters/process/build-config.ts

@@ -0,0 +1,18 @@
+import type { CreateConfigValues } from "../../components/AgentConfigForm";
+
+function parseCommaArgs(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function buildProcessConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.cwd) ac.cwd = v.cwd;
+  ac.timeoutSec = 0;
+  ac.graceSec = 15;
+  if (v.command) ac.command = v.command;
+  if (v.args) ac.args = parseCommaArgs(v.args);
+  return ac;
+}

paperclip-reference/ui/src/adapters/process/config-fields.tsx

@@ -0,0 +1,77 @@
+import type { AdapterConfigFieldsProps } from "../types";
+import {
+  Field,
+  DraftInput,
+  help,
+} from "../../components/agent-config-primitives";
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+
+function formatArgList(value: unknown): string {
+  if (Array.isArray(value)) {
+    return value
+      .filter((item): item is string => typeof item === "string")
+      .join(", ");
+  }
+  return typeof value === "string" ? value : "";
+}
+
+function parseCommaArgs(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+export function ProcessConfigFields({
+  isCreate,
+  values,
+  set,
+  config,
+  eff,
+  mark,
+}: AdapterConfigFieldsProps) {
+  return (
+    <>
+      <Field label="Command" hint={help.command}>
+        <DraftInput
+          value={
+            isCreate
+              ? values!.command
+              : eff("adapterConfig", "command", String(config.command ?? ""))
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ command: v })
+              : mark("adapterConfig", "command", v || undefined)
+          }
+          immediate
+          className={inputClass}
+          placeholder="e.g. node, python"
+        />
+      </Field>
+      <Field label="Args (comma-separated)" hint={help.args}>
+        <DraftInput
+          value={
+            isCreate
+              ? values!.args
+              : eff("adapterConfig", "args", formatArgList(config.args))
+          }
+          onCommit={(v) =>
+            isCreate
+              ? set!({ args: v })
+              : mark(
+                  "adapterConfig",
+                  "args",
+                  v ? parseCommaArgs(v) : undefined,
+                )
+          }
+          immediate
+          className={inputClass}
+          placeholder="e.g. script.js, --flag"
+        />
+      </Field>
+    </>
+  );
+}

paperclip-reference/ui/src/adapters/process/index.ts

@@ -0,0 +1,12 @@
+import type { UIAdapterModule } from "../types";
+import { parseProcessStdoutLine } from "./parse-stdout";
+import { ProcessConfigFields } from "./config-fields";
+import { buildProcessConfig } from "./build-config";
+
+export const processUIAdapter: UIAdapterModule = {
+  type: "process",
+  label: "Shell Process",
+  parseStdoutLine: parseProcessStdoutLine,
+  ConfigFields: ProcessConfigFields,
+  buildAdapterConfig: buildProcessConfig,
+};

paperclip-reference/ui/src/adapters/process/parse-stdout.ts

@@ -0,0 +1,5 @@
+import type { TranscriptEntry } from "../types";
+
+export function parseProcessStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  return [{ kind: "stdout", ts, text: line }];
+}

paperclip-reference/ui/src/adapters/registry.ts

@@ -0,0 +1,34 @@
+import type { UIAdapterModule } from "./types";
+import { claudeLocalUIAdapter } from "./claude-local";
+import { codexLocalUIAdapter } from "./codex-local";
+import { cursorLocalUIAdapter } from "./cursor";
+import { geminiLocalUIAdapter } from "./gemini-local";
+import { openCodeLocalUIAdapter } from "./opencode-local";
+import { piLocalUIAdapter } from "./pi-local";
+import { openClawGatewayUIAdapter } from "./openclaw-gateway";
+import { processUIAdapter } from "./process";
+import { httpUIAdapter } from "./http";
+
+const uiAdapters: UIAdapterModule[] = [
+  claudeLocalUIAdapter,
+  codexLocalUIAdapter,
+  geminiLocalUIAdapter,
+  openCodeLocalUIAdapter,
+  piLocalUIAdapter,
+  cursorLocalUIAdapter,
+  openClawGatewayUIAdapter,
+  processUIAdapter,
+  httpUIAdapter,
+];
+
+const adaptersByType = new Map<string, UIAdapterModule>(
+  uiAdapters.map((a) => [a.type, a]),
+);
+
+export function getUIAdapter(type: string): UIAdapterModule {
+  return adaptersByType.get(type) ?? processUIAdapter;
+}
+
+export function listUIAdapters(): UIAdapterModule[] {
+  return [...uiAdapters];
+}

paperclip-reference/ui/src/adapters/runtime-json-fields.tsx

@@ -0,0 +1,122 @@
+import { useEffect, useState } from "react";
+import type { AdapterConfigFieldsProps } from "./types";
+import { Field, help } from "../components/agent-config-primitives";
+
+// TODO(issue-worktree-support): re-enable this UI once the workflow is ready to ship.
+const SHOW_EXPERIMENTAL_ISSUE_WORKTREE_UI = false;
+
+const inputClass =
+  "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function formatJsonObject(value: unknown): string {
+  const record = asRecord(value);
+  return Object.keys(record).length > 0 ? JSON.stringify(record, null, 2) : "";
+}
+
+function updateJsonConfig(
+  isCreate: boolean,
+  key: "runtimeServicesJson" | "payloadTemplateJson",
+  next: string,
+  set: AdapterConfigFieldsProps["set"],
+  mark: AdapterConfigFieldsProps["mark"],
+  configKey: string,
+) {
+  if (isCreate) {
+    set?.({ [key]: next });
+    return;
+  }
+
+  const trimmed = next.trim();
+  if (!trimmed) {
+    mark("adapterConfig", configKey, undefined);
+    return;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+      mark("adapterConfig", configKey, parsed);
+    }
+  } catch {
+    // Keep local draft until JSON is valid.
+  }
+}
+
+type JsonFieldProps = Pick<
+  AdapterConfigFieldsProps,
+  "isCreate" | "values" | "set" | "config" | "mark"
+>;
+
+export function RuntimeServicesJsonField({
+  isCreate,
+  values,
+  set,
+  config,
+  mark,
+}: JsonFieldProps) {
+  if (!SHOW_EXPERIMENTAL_ISSUE_WORKTREE_UI) {
+    return null;
+  }
+
+  const existing = formatJsonObject(config.workspaceRuntime);
+  const [draft, setDraft] = useState(existing);
+
+  useEffect(() => {
+    if (!isCreate) setDraft(existing);
+  }, [existing, isCreate]);
+
+  const value = isCreate ? values?.runtimeServicesJson ?? "" : draft;
+
+  return (
+    <Field label="Runtime services JSON" hint={help.runtimeServicesJson}>
+      <textarea
+        className={`${inputClass} min-h-[148px]`}
+        value={value}
+        onChange={(e) => {
+          const next = e.target.value;
+          if (!isCreate) setDraft(next);
+          updateJsonConfig(isCreate, "runtimeServicesJson", next, set, mark, "workspaceRuntime");
+        }}
+        placeholder={`{\n  "services": [\n    {\n      "name": "preview",\n      "lifecycle": "ephemeral",\n      "metadata": {\n        "purpose": "remote preview"\n      }\n    }\n  ]\n}`}
+      />
+    </Field>
+  );
+}
+
+export function PayloadTemplateJsonField({
+  isCreate,
+  values,
+  set,
+  config,
+  mark,
+}: JsonFieldProps) {
+  const existing = formatJsonObject(config.payloadTemplate);
+  const [draft, setDraft] = useState(existing);
+
+  useEffect(() => {
+    if (!isCreate) setDraft(existing);
+  }, [existing, isCreate]);
+
+  const value = isCreate ? values?.payloadTemplateJson ?? "" : draft;
+
+  return (
+    <Field label="Payload template JSON" hint={help.payloadTemplateJson}>
+      <textarea
+        className={`${inputClass} min-h-[132px]`}
+        value={value}
+        onChange={(e) => {
+          const next = e.target.value;
+          if (!isCreate) setDraft(next);
+          updateJsonConfig(isCreate, "payloadTemplateJson", next, set, mark, "payloadTemplate");
+        }}
+        placeholder={`{\n  "agentId": "remote-agent-123",\n  "metadata": {\n    "team": "platform"\n  }\n}`}
+      />
+    </Field>
+  );
+}

paperclip-reference/ui/src/adapters/transcript.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { buildTranscript, type RunLogChunk } from "./transcript";
+
+describe("buildTranscript", () => {
+  const ts = "2026-03-20T13:00:00.000Z";
+  const chunks: RunLogChunk[] = [
+    { ts, stream: "stdout", chunk: "opened /Users/dotta/project\n" },
+    { ts, stream: "stderr", chunk: "stderr /Users/dotta/project" },
+  ];
+
+  it("defaults username censoring to off when options are omitted", () => {
+    const entries = buildTranscript(chunks, (line, entryTs) => [{ kind: "stdout", ts: entryTs, text: line }]);
+
+    expect(entries).toEqual([
+      { kind: "stdout", ts, text: "opened /Users/dotta/project" },
+      { kind: "stderr", ts, text: "stderr /Users/dotta/project" },
+    ]);
+  });
+
+  it("still redacts usernames when explicitly enabled", () => {
+    const entries = buildTranscript(chunks, (line, entryTs) => [{ kind: "stdout", ts: entryTs, text: line }], {
+      censorUsernameInLogs: true,
+    });
+
+    expect(entries).toEqual([
+      { kind: "stdout", ts, text: "opened /Users/d****/project" },
+      { kind: "stderr", ts, text: "stderr /Users/d****/project" },
+    ]);
+  });
+});

paperclip-reference/ui/src/adapters/transcript.ts

@@ -0,0 +1,61 @@
+import { redactHomePathUserSegments, redactTranscriptEntryPaths } from "@paperclipai/adapter-utils";
+import type { TranscriptEntry, StdoutLineParser } from "./types";
+
+export type RunLogChunk = { ts: string; stream: "stdout" | "stderr" | "system"; chunk: string };
+type TranscriptBuildOptions = { censorUsernameInLogs?: boolean };
+
+export function appendTranscriptEntry(entries: TranscriptEntry[], entry: TranscriptEntry) {
+  if ((entry.kind === "thinking" || entry.kind === "assistant") && entry.delta) {
+    const last = entries[entries.length - 1];
+    if (last && last.kind === entry.kind && last.delta) {
+      last.text += entry.text;
+      last.ts = entry.ts;
+      return;
+    }
+  }
+  entries.push(entry);
+}
+
+export function appendTranscriptEntries(entries: TranscriptEntry[], incoming: TranscriptEntry[]) {
+  for (const entry of incoming) {
+    appendTranscriptEntry(entries, entry);
+  }
+}
+
+export function buildTranscript(
+  chunks: RunLogChunk[],
+  parser: StdoutLineParser,
+  opts?: TranscriptBuildOptions,
+): TranscriptEntry[] {
+  const entries: TranscriptEntry[] = [];
+  let stdoutBuffer = "";
+  const redactionOptions = { enabled: opts?.censorUsernameInLogs ?? false };
+
+  for (const chunk of chunks) {
+    if (chunk.stream === "stderr") {
+      entries.push({ kind: "stderr", ts: chunk.ts, text: redactHomePathUserSegments(chunk.chunk, redactionOptions) });
+      continue;
+    }
+    if (chunk.stream === "system") {
+      entries.push({ kind: "system", ts: chunk.ts, text: redactHomePathUserSegments(chunk.chunk, redactionOptions) });
+      continue;
+    }
+
+    const combined = stdoutBuffer + chunk.chunk;
+    const lines = combined.split(/\r?\n/);
+    stdoutBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      appendTranscriptEntries(entries, parser(trimmed, chunk.ts).map((entry) => redactTranscriptEntryPaths(entry, redactionOptions)));
+    }
+  }
+
+  const trailing = stdoutBuffer.trim();
+  if (trailing) {
+    const ts = chunks.length > 0 ? chunks[chunks.length - 1]!.ts : new Date().toISOString();
+    appendTranscriptEntries(entries, parser(trailing, ts).map((entry) => redactTranscriptEntryPaths(entry, redactionOptions)));
+  }
+
+  return entries;
+}

paperclip-reference/ui/src/adapters/types.ts

@@ -0,0 +1,33 @@
+import type { ComponentType } from "react";
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+// Re-export shared types so local consumers don't need to change imports
+export type { TranscriptEntry, StdoutLineParser, CreateConfigValues } from "@paperclipai/adapter-utils";
+
+export interface AdapterConfigFieldsProps {
+  mode: "create" | "edit";
+  isCreate: boolean;
+  adapterType: string;
+  /** Create mode: raw form values */
+  values: CreateConfigValues | null;
+  /** Create mode: setter for form values */
+  set: ((patch: Partial<CreateConfigValues>) => void) | null;
+  /** Edit mode: original adapterConfig from agent */
+  config: Record<string, unknown>;
+  /** Edit mode: read effective value */
+  eff: <T>(group: "adapterConfig", field: string, original: T) => T;
+  /** Edit mode: mark field dirty */
+  mark: (group: "adapterConfig", field: string, value: unknown) => void;
+  /** Available models for dropdowns */
+  models: { id: string; label: string }[];
+  /** When true, hides the instructions file path field (e.g. during import where it's set automatically) */
+  hideInstructionsFile?: boolean;
+}
+
+export interface UIAdapterModule {
+  type: string;
+  label: string;
+  parseStdoutLine: (line: string, ts: string) => import("@paperclipai/adapter-utils").TranscriptEntry[];
+  ConfigFields: ComponentType<AdapterConfigFieldsProps>;
+  buildAdapterConfig: (values: CreateConfigValues) => Record<string, unknown>;
+}