@smithers-orchestrator/pi-plugin 0.16.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@smithers-orchestrator/pi-plugin",
+  "version": "0.16.9",
+  "description": "PI coding agent integration for Smithers workflow inspection",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./extension": {
+      "types": "./src/extension.ts",
+      "import": "./src/extension.ts",
+      "default": "./src/extension.ts"
+    },
+    "./runtime/*": {
+      "types": "./src/runtime/*.ts",
+      "import": "./src/runtime/*.ts",
+      "default": "./src/runtime/*.ts"
+    },
+    "./views/*": {
+      "types": "./src/views/*.ts",
+      "import": "./src/views/*.ts",
+      "default": "./src/views/*.ts"
+    },
+    "./api/*": {
+      "types": "./src/api/*.ts",
+      "import": "./src/api/*.ts",
+      "default": "./src/api/*.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sinclair/typebox": "^0.34.49",
+    "ws": "^8.20.0",
+    "@smithers-orchestrator/agents": "0.16.9",
+    "@smithers-orchestrator/cli": "0.16.9",
+    "@smithers-orchestrator/devtools": "0.16.9",
+    "@smithers-orchestrator/errors": "0.16.9",
+    "@smithers-orchestrator/protocol": "0.16.9"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/ws": "^8.18.1",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/SmithersPiRunContext.ts

@@ -0,0 +1,7 @@
+export type SmithersPiRunContext = {
+	runId: string;
+	workflowName: string;
+	status: string;
+	nodeStates: Array<{ nodeId: string; state: string }>;
+	errors: string[];
+};

package/src/api/SmithersPiHttpClient.ts

@@ -0,0 +1,86 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+type RequestOptions = {
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+type FetchOptions = {
+  method?: string;
+  body?: unknown;
+};
+
+const DEFAULT_BASE = "http://127.0.0.1:7331";
+
+function buildHeaders(opts: RequestOptions, withJson: boolean) {
+  const headers: Record<string, string> = {};
+  if (withJson) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (opts.apiKey) {
+    headers.Authorization = `Bearer ${opts.apiKey}`;
+  }
+  return headers;
+}
+
+export class SmithersPiHttpClient {
+  readonly baseUrl: string;
+  readonly apiKey: string | undefined;
+
+  constructor(opts: RequestOptions = {}) {
+    this.baseUrl = opts.baseUrl ?? DEFAULT_BASE;
+    this.apiKey = opts.apiKey;
+  }
+
+  async json(path: string, opts: FetchOptions = {}) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: opts.method ?? "GET",
+      headers: buildHeaders(this, opts.body !== undefined),
+      body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new SmithersError(
+        "PI_HTTP_ERROR",
+        `Smithers HTTP ${res.status}${text ? `: ${text}` : ""}`,
+        {
+          baseUrl: this.baseUrl,
+          path,
+          status: res.status,
+        },
+      );
+    }
+    return res.json();
+  }
+
+  async *events(path: string) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      headers: buildHeaders(this, false),
+    });
+    if (!res.ok || !res.body) {
+      return;
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      buffer += decoder.decode(value, { stream: true });
+      const parts = buffer.split("\n\n");
+      buffer = parts.pop() ?? "";
+
+      for (const part of parts) {
+        const line = part.split("\n").find((item) => item.startsWith("data: "));
+        if (line) {
+          yield JSON.parse(line.slice(6));
+        }
+      }
+    }
+  }
+}

package/src/api/approve.ts

@@ -0,0 +1,23 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type ApproveArgs = {
+  runId: string;
+  nodeId: string;
+  iteration?: number;
+  note?: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function approve(args: ApproveArgs) {
+  return new SmithersPiHttpClient(args).json(
+    `/v1/runs/${args.runId}/nodes/${args.nodeId}/approve`,
+    {
+      method: "POST",
+      body: {
+        iteration: args.iteration ?? 0,
+        note: args.note,
+      },
+    },
+  );
+}

package/src/api/cancel.ts

@@ -0,0 +1,14 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type CancelArgs = {
+  runId: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function cancel(args: CancelArgs) {
+  return new SmithersPiHttpClient(args).json(`/v1/runs/${args.runId}/cancel`, {
+    method: "POST",
+    body: {},
+  });
+}

package/src/api/deny.ts

@@ -0,0 +1,23 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type DenyArgs = {
+  runId: string;
+  nodeId: string;
+  iteration?: number;
+  note?: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function deny(args: DenyArgs) {
+  return new SmithersPiHttpClient(args).json(
+    `/v1/runs/${args.runId}/nodes/${args.nodeId}/deny`,
+    {
+      method: "POST",
+      body: {
+        iteration: args.iteration ?? 0,
+        note: args.note,
+      },
+    },
+  );
+}

package/src/api/getFrames.ts

@@ -0,0 +1,14 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type GetFramesArgs = {
+  runId: string;
+  tail?: number;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function getFrames(args: GetFramesArgs) {
+  return new SmithersPiHttpClient(args).json(
+    `/v1/runs/${args.runId}/frames?limit=${args.tail ?? 20}`,
+  );
+}

package/src/api/getStatus.ts

@@ -0,0 +1,11 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type GetStatusArgs = {
+  runId: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function getStatus(args: GetStatusArgs) {
+  return new SmithersPiHttpClient(args).json(`/v1/runs/${args.runId}`);
+}

package/src/api/listRuns.ts

@@ -0,0 +1,20 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type ListRunsArgs = {
+  limit?: number;
+  status?: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function listRuns(args: ListRunsArgs = {}) {
+  const params = new URLSearchParams();
+  if (args.limit !== undefined) {
+    params.set("limit", String(args.limit));
+  }
+  if (args.status) {
+    params.set("status", args.status);
+  }
+  const query = params.toString();
+  return new SmithersPiHttpClient(args).json(`/v1/runs${query ? `?${query}` : ""}`);
+}

package/src/api/resume.ts

@@ -0,0 +1,19 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type ResumeArgs = {
+  workflowPath: string;
+  runId: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function resume(args: ResumeArgs) {
+  return new SmithersPiHttpClient(args).json("/v1/runs", {
+    method: "POST",
+    body: {
+      workflowPath: args.workflowPath,
+      runId: args.runId,
+      resume: true,
+    },
+  });
+}

package/src/api/runWorkflow.ts

@@ -0,0 +1,20 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type RunWorkflowArgs = {
+  workflowPath: string;
+  input: unknown;
+  runId?: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function runWorkflow(args: RunWorkflowArgs) {
+  return new SmithersPiHttpClient(args).json("/v1/runs", {
+    method: "POST",
+    body: {
+      workflowPath: args.workflowPath,
+      input: args.input,
+      runId: args.runId,
+    },
+  });
+}

package/src/api/streamEvents.ts

@@ -0,0 +1,11 @@
+import { SmithersPiHttpClient } from "./SmithersPiHttpClient.js";
+
+type StreamEventsArgs = {
+  runId: string;
+  baseUrl?: string;
+  apiKey?: string;
+};
+
+export async function* streamEvents(args: StreamEventsArgs) {
+  yield* new SmithersPiHttpClient(args).events(`/v1/runs/${args.runId}/events`);
+}

package/src/buildSmithersPiSystemPrompt.ts

@@ -0,0 +1,120 @@
+import {
+  renderSmithersAgentPromptGuidance,
+  type SmithersAgentContract,
+} from "@smithers-orchestrator/agents/agent-contract";
+import type { SmithersPiRunContext } from "./SmithersPiRunContext.js";
+
+function toolRef(contract: SmithersAgentContract, name: string, prefix = "smithers_") {
+  return contract.tools.some((tool) => tool.name === name) ? `\`${prefix}${name}\`` : undefined;
+}
+
+function buildTypicalWorkflowGuidance(contract: SmithersAgentContract) {
+  const discover = toolRef(contract, "list_workflows");
+  const run = toolRef(contract, "run_workflow");
+  const listRuns = toolRef(contract, "list_runs");
+  const getRun = toolRef(contract, "get_run");
+  const watchRun = toolRef(contract, "watch_run");
+  const explainRun = toolRef(contract, "explain_run");
+  const listApprovals = toolRef(contract, "list_pending_approvals");
+  const resolveApproval = toolRef(contract, "resolve_approval");
+  const getNodeDetail = toolRef(contract, "get_node_detail");
+  const getRunEvents = toolRef(contract, "get_run_events");
+  const listArtifacts = toolRef(contract, "list_artifacts");
+  const getTranscript = toolRef(contract, "get_chat_transcript");
+  const revertAttempt = toolRef(contract, "revert_attempt");
+  const steps = [
+    "**Write a workflow** -> Use your Smithers knowledge to help the user write workflow files.",
+  ];
+
+  if (discover && run) {
+    steps.push(`**Run it** -> Use ${discover} to find workflow IDs, then ${run} to launch the workflow.`);
+  } else if (run) {
+    steps.push(`**Run it** -> Use ${run} to launch the workflow.`);
+  }
+
+  const monitorTools = [listRuns, getRun, watchRun, explainRun].filter(Boolean);
+  if (monitorTools.length > 0) {
+    steps.push(
+      `**Monitor** -> Use ${monitorTools.join(", ")} to inspect progress, or tell the user about \`/smithers\`.`,
+    );
+  }
+
+  const approvalTools = [listApprovals, resolveApproval].filter(Boolean);
+  if (approvalTools.length > 0) {
+    steps.push(`**Approve** -> Use ${approvalTools.join(", ")} when runs are waiting for approval.`);
+  }
+
+  const debugTools = [getNodeDetail, getRunEvents, listArtifacts, getTranscript].filter(Boolean);
+  if (debugTools.length > 0) {
+    steps.push(`**Debug** -> Use ${debugTools.join(", ")} to gather evidence before changing anything.`);
+  }
+
+  if (revertAttempt) {
+    steps.push(
+      `**Revert** -> Use ${revertAttempt} only when the user explicitly asks to roll back or time travel.`,
+    );
+  }
+
+  return steps.map((step, index) => `${index + 1}. ${step}`);
+}
+
+export function buildSmithersPiSystemPrompt(
+  baseSystemPrompt: string,
+  docs: string,
+  contract: SmithersAgentContract,
+  activeRun?: SmithersPiRunContext,
+) {
+  const sections = [
+    "\n\n# Smithers Documentation\n",
+    "You are a Smithers workflow expert. Prefer the live Smithers tools over shelling out when they can answer the request.\n",
+    "## Smithers PI Extension - User Guide\n",
+    "The user is running PI with the Smithers extension. When they ask about capabilities, slash commands, or how to use this environment, refer to this section.\n",
+    "### Tools (available to you, the agent)",
+    renderSmithersAgentPromptGuidance(contract, { toolNamePrefix: "smithers_" }),
+    "",
+    "### Slash Commands (available to the user)",
+    "Tell the user about these when they ask what they can do:",
+    "- `/smithers` - Opens the live run inspector with a virtualized tree, frame scrubber, Output/Diff/Logs inspector tabs, heartbeat indicators, and ghost node badges.",
+    "- `/smithers-watch <runId>` - Attaches the inspector and event stream to a run by ID.",
+    "- `/smithers-runs` - Lists tracked runs and makes the selected run active.",
+    "- `/smithers-approve` - Interactive approval flow for nodes waiting on approval.",
+    "- `/smithers-cancel [runId]` - Cancels a running workflow with confirmation.",
+    "",
+    "### UI Features (always active)",
+    "- **Header**: Shows run state, the active run ID, engine and sandbox/viewer heartbeat indicators, and reconnect status.",
+    "- **Tree**: Left pane virtualized run tree. Failed descendants bubble an error marker to collapsed ancestors, and removed selected nodes stay inspectable as ghosts.",
+    "- **Inspector**: Right pane Output, Diff, and Logs tabs for the selected node.",
+    "- **Frame Scrubber**: Browse historical frames and return to live mode.",
+    "- **Stale Banner**: Appears while the gateway stream is disconnected long enough that the displayed tree may be stale.",
+    "",
+    "### Flags (passed via CLI)",
+    "- `--smithers-url` / `-u` - Smithers server or gateway URL (default: http://127.0.0.1:7331)",
+    "- `--smithers-key` / `-k` - Smithers API key (also reads SMITHERS_API_KEY env var)",
+    "",
+    "### Typical Workflows",
+    ...buildTypicalWorkflowGuidance(contract),
+    "",
+    "---\n",
+    docs,
+  ];
+
+  if (activeRun) {
+    sections.push("\n## Active Run Context");
+    sections.push(`Run: ${activeRun.runId} (${activeRun.workflowName})`);
+    sections.push(`Status: ${activeRun.status}`);
+
+    const waitingNodes = activeRun.nodeStates.filter(
+      (node) => node.state === "waiting-approval" || node.state === "waiting-timer",
+    );
+    if (waitingNodes.length > 0) {
+      sections.push(`Nodes waiting approval: ${waitingNodes.map((node) => node.nodeId).join(", ")}`);
+    }
+
+    const recentErrors = activeRun.errors.slice(-3);
+    if (recentErrors.length > 0) {
+      sections.push(`Recent errors: ${recentErrors.join("; ")}`);
+    }
+  }
+
+  return baseSystemPrompt + sections.join("\n");
+}