Add worktree-aware workspace runtime support

2026-03-10 10:58:38 -05:00
parent 7934952a77
commit 3120c72372
35 changed files with 8750 additions and 61 deletions
--- a/ui/src/adapters/claude-local/config-fields.tsx
+++ b/ui/src/adapters/claude-local/config-fields.tsx
@@ -7,6 +7,7 @@ import {
  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";
@@ -15,38 +16,54 @@ 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,
 }: AdapterConfigFieldsProps) {
  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>
+    <>
+      <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}
+      />
+    </>
  );
 }

--- a/ui/src/adapters/codex-local/config-fields.tsx
+++ b/ui/src/adapters/codex-local/config-fields.tsx
@@ -6,6 +6,7 @@ import {
  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";
@@ -13,12 +14,15 @@ 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 CodexLocalConfigFields({
+  mode,
  isCreate,
+  adapterType,
  values,
  set,
  config,
  eff,
  mark,
+  models,
 }: AdapterConfigFieldsProps) {
  const bypassEnabled =
    config.dangerouslyBypassApprovalsAndSandbox === true || config.dangerouslyBypassSandbox === true;
@@ -81,6 +85,17 @@ export function CodexLocalConfigFields({
            : mark("adapterConfig", "search", v)
        }
      />
+      <LocalWorkspaceRuntimeFields
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+        eff={eff}
+        mode={mode}
+        adapterType={adapterType}
+        models={models}
+      />
    </>
  );
 }
--- a/ui/src/adapters/local-workspace-runtime-fields.tsx
+++ b/ui/src/adapters/local-workspace-runtime-fields.tsx
@@ -0,0 +1,136 @@
+import type { AdapterConfigFieldsProps } from "./types";
+import { DraftInput, Field, help } from "../components/agent-config-primitives";
+import { 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 asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function readWorkspaceStrategy(config: Record<string, unknown>) {
+  const strategy = asRecord(config.workspaceStrategy);
+  const type = asString(strategy.type) || "project_primary";
+  return {
+    type,
+    baseRef: asString(strategy.baseRef),
+    branchTemplate: asString(strategy.branchTemplate),
+    worktreeParentDir: asString(strategy.worktreeParentDir),
+  };
+}
+
+function buildWorkspaceStrategyPatch(input: {
+  type: string;
+  baseRef?: string;
+  branchTemplate?: string;
+  worktreeParentDir?: string;
+}) {
+  if (input.type !== "git_worktree") return undefined;
+  return {
+    type: "git_worktree",
+    ...(input.baseRef ? { baseRef: input.baseRef } : {}),
+    ...(input.branchTemplate ? { branchTemplate: input.branchTemplate } : {}),
+    ...(input.worktreeParentDir ? { worktreeParentDir: input.worktreeParentDir } : {}),
+  };
+}
+
+export function LocalWorkspaceRuntimeFields({
+  isCreate,
+  values,
+  set,
+  config,
+  mark,
+}: AdapterConfigFieldsProps) {
+  const existing = readWorkspaceStrategy(config);
+  const strategyType = isCreate ? values!.workspaceStrategyType ?? "project_primary" : existing.type;
+  const updateEditWorkspaceStrategy = (patch: Partial<typeof existing>) => {
+    const next = {
+      ...existing,
+      ...patch,
+    };
+    mark(
+      "adapterConfig",
+      "workspaceStrategy",
+      buildWorkspaceStrategyPatch(next),
+    );
+  };
+  return (
+    <>
+      <Field label="Workspace strategy" hint={help.workspaceStrategy}>
+        <select
+          className={inputClass}
+          value={strategyType}
+          onChange={(e) => {
+            const nextType = e.target.value;
+            if (isCreate) {
+              set!({ workspaceStrategyType: nextType });
+            } else {
+              updateEditWorkspaceStrategy({ type: nextType });
+            }
+          }}
+        >
+          <option value="project_primary">Project primary workspace</option>
+          <option value="git_worktree">Git worktree</option>
+        </select>
+      </Field>
+
+      {strategyType === "git_worktree" && (
+        <>
+          <Field label="Base ref" hint={help.workspaceBaseRef}>
+            <DraftInput
+              value={isCreate ? values!.workspaceBaseRef ?? "" : existing.baseRef}
+              onCommit={(v) =>
+                isCreate
+                  ? set!({ workspaceBaseRef: v })
+                  : updateEditWorkspaceStrategy({ baseRef: v || "" })
+              }
+              immediate
+              className={inputClass}
+              placeholder="origin/main"
+            />
+          </Field>
+          <Field label="Branch template" hint={help.workspaceBranchTemplate}>
+            <DraftInput
+              value={isCreate ? values!.workspaceBranchTemplate ?? "" : existing.branchTemplate}
+              onCommit={(v) =>
+                isCreate
+                  ? set!({ workspaceBranchTemplate: v })
+                  : updateEditWorkspaceStrategy({ branchTemplate: v || "" })
+              }
+              immediate
+              className={inputClass}
+              placeholder="{{issue.identifier}}-{{slug}}"
+            />
+          </Field>
+          <Field label="Worktree parent dir" hint={help.worktreeParentDir}>
+            <DraftInput
+              value={isCreate ? values!.worktreeParentDir ?? "" : existing.worktreeParentDir}
+              onCommit={(v) =>
+                isCreate
+                  ? set!({ worktreeParentDir: v })
+                  : updateEditWorkspaceStrategy({ worktreeParentDir: v || "" })
+              }
+              immediate
+              className={inputClass}
+              placeholder=".paperclip/worktrees"
+            />
+          </Field>
+        </>
+      )}
+      <RuntimeServicesJsonField
+        isCreate={isCreate}
+        values={values}
+        set={set}
+        config={config}
+        mark={mark}
+      />
+    </>
+  );
+}
--- a/ui/src/adapters/openclaw-gateway/config-fields.tsx
+++ b/ui/src/adapters/openclaw-gateway/config-fields.tsx
@@ -6,6 +6,10 @@ import {
  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";
@@ -112,6 +116,22 @@ export function OpenClawGatewayConfigFields({
        />
      </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">
--- a/ui/src/adapters/runtime-json-fields.tsx
+++ b/ui/src/adapters/runtime-json-fields.tsx
@@ -0,0 +1,115 @@
+import { useEffect, useState } from "react";
+import type { AdapterConfigFieldsProps } from "./types";
+import { Field, 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 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) {
+  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>
+  );
+}
--- a/ui/src/components/ProjectProperties.tsx
+++ b/ui/src/components/ProjectProperties.tsx
@@ -407,6 +407,51 @@ export function ProjectProperties({ project, onUpdate }: ProjectPropertiesProps)
                      </Button>
                    </div>
                  ) : null}
+                  {workspace.runtimeServices && workspace.runtimeServices.length > 0 ? (
+                    <div className="space-y-1 pl-2">
+                      {workspace.runtimeServices.map((service) => (
+                        <div
+                          key={service.id}
+                          className="flex items-center justify-between gap-2 rounded-md border border-border/60 px-2 py-1"
+                        >
+                          <div className="min-w-0 space-y-0.5">
+                            <div className="flex items-center gap-2">
+                              <span className="text-[11px] font-medium">{service.serviceName}</span>
+                              <span
+                                className={cn(
+                                  "rounded-full px-1.5 py-0.5 text-[10px] uppercase tracking-wide",
+                                  service.status === "running"
+                                    ? "bg-green-500/15 text-green-700 dark:text-green-300"
+                                    : service.status === "failed"
+                                      ? "bg-red-500/15 text-red-700 dark:text-red-300"
+                                      : "bg-muted text-muted-foreground",
+                                )}
+                              >
+                                {service.status}
+                              </span>
+                            </div>
+                            <div className="text-[11px] text-muted-foreground">
+                              {service.url ? (
+                                <a
+                                  href={service.url}
+                                  target="_blank"
+                                  rel="noreferrer"
+                                  className="hover:text-foreground hover:underline"
+                                >
+                                  {service.url}
+                                </a>
+                              ) : (
+                                service.command ?? "No URL"
+                              )}
+                            </div>
+                          </div>
+                          <div className="text-[10px] text-muted-foreground whitespace-nowrap">
+                            {service.lifecycle}
+                          </div>
+                        </div>
+                      ))}
+                    </div>
+                  ) : null}
                </div>
              ))}
            </div>
--- a/ui/src/components/agent-config-defaults.ts
+++ b/ui/src/components/agent-config-defaults.ts
@@ -18,6 +18,12 @@ export const defaultCreateValues: CreateConfigValues = {
  envBindings: {},
  url: "",
  bootstrapPrompt: "",
+  payloadTemplateJson: "",
+  workspaceStrategyType: "project_primary",
+  workspaceBaseRef: "",
+  workspaceBranchTemplate: "",
+  worktreeParentDir: "",
+  runtimeServicesJson: "",
  maxTurnsPerRun: 80,
  heartbeatEnabled: false,
  intervalSec: 300,
--- a/ui/src/components/agent-config-primitives.tsx
+++ b/ui/src/components/agent-config-primitives.tsx
@@ -33,12 +33,19 @@ export const help: Record<string, string> = {
  dangerouslySkipPermissions: "Run Claude without permission prompts. Required for unattended operation.",
  dangerouslyBypassSandbox: "Run Codex without sandbox restrictions. Required for filesystem/network access.",
  search: "Enable Codex web search capability during runs.",
+  workspaceStrategy: "How Paperclip should realize an execution workspace for this agent. Keep project_primary for normal cwd execution, or use git_worktree for issue-scoped isolated checkouts.",
+  workspaceBaseRef: "Base git ref used when creating a worktree branch. Leave blank to use the resolved workspace ref or HEAD.",
+  workspaceBranchTemplate: "Template for naming derived branches. Supports {{issue.identifier}}, {{issue.title}}, {{agent.name}}, {{project.id}}, {{workspace.repoRef}}, and {{slug}}.",
+  worktreeParentDir: "Directory where derived worktrees should be created. Absolute, ~-prefixed, and repo-relative paths are supported.",
+  runtimeServicesJson: "Optional workspace runtime service definitions. Use this for shared app servers, workers, or other long-lived companion processes attached to the workspace.",
  maxTurnsPerRun: "Maximum number of agentic turns (tool calls) per heartbeat run.",
  command: "The command to execute (e.g. node, python).",
  localCommand: "Override the path to the CLI command you want the adapter to call (e.g. /usr/local/bin/claude, codex, opencode).",
  args: "Command-line arguments, comma-separated.",
  extraArgs: "Extra CLI arguments for local adapters, comma-separated.",
  envVars: "Environment variables injected into the adapter process. Use plain values or secret references.",
+  bootstrapPrompt: "Optional prompt prepended on the first run to bootstrap the agent's environment or habits.",
+  payloadTemplateJson: "Optional JSON merged into remote adapter request payloads before Paperclip adds its standard wake and workspace fields.",
  webhookUrl: "The URL that receives POST requests when the agent is invoked.",
  heartbeatInterval: "Run this agent automatically on a timer. Useful for periodic tasks like checking for new work.",
  intervalSec: "Seconds between automatic heartbeat invocations.",