pi-factory-gate 1.0.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# Factory Gate — Agent Usage Guide
+
+> You are an AI agent. Use factory-gate tools to interact with the wrok.in AI Factory orchestrator.
+
+## Quickstart
+
+```bash
+factory_status()                         # Check factory health
+factory_list_agents()                    # See available agents
+factory_create_job(mode="single", agent="code-reviewer", task="Review the diff")
+factory_stream_job(id="<job-id>")        # Wait for completion
+```
+
+## Job Modes
+
+- **single** — one agent, one task: `factory_create_job(mode="single", agent="analyzer", task="Analyze the codebase")`
+- **chain** — sequential agents: `factory_create_job(mode="chain", steps='[{"agent":"planner","task":"Plan"},{"agent":"builder","task":"Build"}]')`
+- **parallel** — concurrent agents: `factory_create_job(mode="parallel", tasks='[{"agent":"linter","task":"Lint"},{"agent":"tester","task":"Test"}]')`
+
+## Environments
+
+```bash
+factory_list_environments()                  # List registered environments
+factory_create_environment(name="app", repo="https://github.com/user/app.git")
+factory_create_job(mode="single", agent="builder", task="Build", environment="app")
+```
+
+Skip environments with direct repo dispatch:
+```bash
+factory_create_job(mode="single", agent="analyzer", task="Analyze", repo="https://github.com/user/repo.git", branch="main")
+```
+
+## Workflows & Monitoring
+
+```bash
+factory_list_workflows()                     # List workflow templates
+factory_run_workflow(template="ci-review")   # Execute a workflow
+factory_list_workers()                       # Worker health
+factory_get_events()                         # Recent system events
+```
+
+## Job Lifecycle
+
+```
+factory_create_job(...)
+  │
+  ▼
+factory_get_job(id="...")     ← check status anytime
+  │
+  ▼
+factory_stream_job(id="...")  ← wait for completion
+  │
+  ▼
+[result]                       ← final state: completed | failed | partial
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `factory_status()` fails | Check that the orchestrator is running. Verify `.factoryrc.yml` has the correct `orchestratorUrl`. |
+| Job stays "pending" | All workers are busy or offline. Check `factory_list_workers()`. |
+| "Environment not found" | Run `factory_list_environments()` to see what's available, or create one with `factory_create_environment()`. |
+| 409 Conflict on job create | An exclusive agent is already working on the same branch. Wait for it to complete or use `force: true`. |
+| 503 "Job creation disabled" | Jobs are toggled off in the factory dashboard. Toggle "Jobs On" to re-enable. |
+| "Agent not found" | Run `factory_list_agents()` to see available agents. Check the environment context. |
+
+## Config Reference
+
+`.factoryrc.yml`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `orchestratorUrl` | `http://localhost:3001` | Factory orchestrator URL |
+| `defaultEnvironment` | (none) | Default environment for jobs |
+| `defaultLimit` | `20` | Items per list operation |
+| `requestTimeout` | `15000` | API timeout in ms |
+| `maxLogLines` | `500` | Max output lines for streaming |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+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/README.md

@@ -0,0 +1,83 @@
+# pi-factory-gate
+
+AI Factory orchestration gateway for pi agents — dispatch jobs, manage environments, list agents/workers/workflows, and stream results from a [wrok.in](https://github.com/nandal/wrok.in) orchestrator.
+
+## Install
+
+```bash
+pi install npm:pi-factory-gate
+```
+
+## Configuration
+
+Add a `.factoryrc.yml` to your repo root:
+
+```yaml
+orchestratorUrl: http://localhost:3001
+defaultEnvironment: default
+defaultLimit: 20
+requestTimeout: 15000
+maxLogLines: 500
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `orchestratorUrl` | `http://localhost:3001` | Base URL of the wrok.in orchestrator |
+| `defaultEnvironment` | (none) | Default environment for job dispatch |
+| `defaultLimit` | `20` | Default page size for list operations |
+| `requestTimeout` | `15000` | API call timeout in ms |
+| `maxLogLines` | `500` | Max lines for streamed job output |
+
+## Tools
+
+### Agents
+
+| Tool | Description |
+|------|-------------|
+| `factory_list_agents` | List all agents, optionally filtered by environment |
+| `factory_get_agent` | Get agent detail including inheritance and resolved config |
+
+### Jobs
+
+| Tool | Description |
+|------|-------------|
+| `factory_create_job` | Dispatch a job (single, chain, or parallel mode) |
+| `factory_get_job` | Get job status and results |
+| `factory_list_jobs` | List all jobs in the factory |
+| `factory_stream_job` | Poll for completion, returns final state |
+
+### Environments
+
+| Tool | Description |
+|------|-------------|
+| `factory_list_environments` | List all registered environments |
+| `factory_get_environment` | Get environment detail |
+| `factory_create_environment` | Register a new environment (clone a repo) |
+
+### Workers
+
+| Tool | Description |
+|------|-------------|
+| `factory_list_workers` | List all workers with health/status |
+
+### Workflows
+
+| Tool | Description |
+|------|-------------|
+| `factory_list_workflows` | List workflow templates (DB + disk discovery) |
+| `factory_run_workflow` | Execute a workflow template |
+
+### Events & Status
+
+| Tool | Description |
+|------|-------------|
+| `factory_get_events` | Get recent system events |
+| `factory_status` | Health check — is the orchestrator reachable? |
+
+## About wrok.in
+
+This gate works with the [wrok.in](https://github.com/nandal/wrok.in) AI Factory — a personal AI workflow orchestrator that manages pi workers across Docker containers with multi-repo environments, agent inheritance, DB-backed agents, and workflow scheduling.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pi-factory-gate",
+  "version": "1.0.0",
+  "description": "AI Factory gateway for pi agents — dispatch jobs, manage environments, list agents/workers/workflows, stream results from a wrok.in orchestrator.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ai-factory",
+    "orchestrator",
+    "agent-management",
+    "job-dispatch",
+    "workflow"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "factory-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/factory-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
+  }
+}

package/src/config.ts

@@ -0,0 +1,32 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { FactoryConfig } from "./types";
+import { DEFAULT_CONFIG } from "./types";
+
+export function loadConfig(cwd: string): FactoryConfig {
+  const configPath = path.join(cwd, ".factoryrc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*(\w[\w.]*):\s*(.+)$/);
+      if (m) {
+        let val = m[2].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        result[m[1]] = val;
+      }
+    }
+    return {
+      orchestratorUrl: (result["orchestratorUrl"] as string) || DEFAULT_CONFIG.orchestratorUrl,
+      defaultEnvironment: (result["defaultEnvironment"] as string) || DEFAULT_CONFIG.defaultEnvironment,
+      defaultLimit: parseInt(result["defaultLimit"] as string) || DEFAULT_CONFIG.defaultLimit,
+      requestTimeout: parseInt(result["requestTimeout"] as string) || DEFAULT_CONFIG.requestTimeout,
+      maxLogLines: parseInt(result["maxLogLines"] as string) || DEFAULT_CONFIG.maxLogLines,
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,114 @@
+import type { FactoryConfig } from "./types";
+
+/**
+ * Call the wrok.in orchestrator API.
+ * Handles JSON parsing, error extraction, and timeouts.
+ */
+export async function factoryApi<T = unknown>(
+  config: FactoryConfig,
+  endpoint: string,
+  method: "GET" | "POST" | "DELETE" = "GET",
+  body?: unknown,
+): Promise<{ ok: boolean; data?: T; error?: string; status: number }> {
+  const url = `${config.orchestratorUrl.replace(/\/$/, "")}${endpoint}`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.requestTimeout);
+
+  try {
+    const opts: RequestInit = {
+      method,
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      signal: controller.signal,
+    };
+    if (body !== undefined && method !== "GET") {
+      opts.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(url, opts);
+    clearTimeout(timeout);
+
+    const contentType = res.headers.get("content-type") || "";
+    const isJson = contentType.includes("application/json");
+
+    if (!res.ok) {
+      const errBody = isJson ? await res.json().catch(() => null) : await res.text().catch(() => null);
+      const msg = errBody && typeof errBody === "object" && "error" in errBody
+        ? String((errBody as Record<string, unknown>).error)
+        : String(errBody || res.statusText);
+      return { ok: false, error: msg, status: res.status };
+    }
+
+    if (isJson) {
+      const data = await res.json() as T;
+      return { ok: true, data, status: res.status };
+    }
+
+    const text = await res.text();
+    return { ok: true, data: text as unknown as T, status: res.status };
+  } catch (err: unknown) {
+    clearTimeout(timeout);
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("abort") || msg.includes("timeout")) {
+      return { ok: false, error: `Request timed out after ${config.requestTimeout}ms`, status: 0 };
+    }
+    return { ok: false, error: msg, status: 0 };
+  }
+}
+
+/**
+ * Format a Unix timestamp into a human-readable string.
+ */
+export function formatTimestamp(ts: number): string {
+  return new Date(ts).toISOString().slice(0, 19).replace("T", " ");
+}
+
+/**
+ * Format duration in ms to a human-readable string.
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.floor(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${s % 60}s`;
+  const h = Math.floor(m / 60);
+  return `${h}h ${m % 60}m`;
+}
+
+/**
+ * Truncate a long string, keeping head and tail for readability.
+ */
+export function truncateOutput(text: string, maxLines: number): { text: string; truncated: boolean; totalLines: number } {
+  const lines = text.split("\n");
+  const totalLines = lines.length;
+  if (totalLines <= maxLines) return { text, truncated: false, totalLines };
+
+  const head = Math.ceil(maxLines * 0.6);
+  const tail = maxLines - head;
+  const truncated =
+    lines.slice(0, head).join("\n") +
+    `\n\n... [${totalLines - maxLines} lines truncated] ...\n\n` +
+    lines.slice(-tail).join("\n");
+
+  return { text: truncated, truncated: true, totalLines };
+}
+
+/**
+ * Status icon helper for job/worker display.
+ */
+export function statusIcon(status: string): string {
+  const s = status.toLowerCase();
+  if (s === "running" || s === "in_progress") return "🔄";
+  if (s === "pending" || s === "queued") return "⏳";
+  if (s === "completed" || s === "success") return "✅";
+  if (s === "failed" || s === "failure") return "❌";
+  if (s === "partial") return "⚠️";
+  if (s === "busy") return "🔵";
+  if (s === "idle") return "🟢";
+  if (s === "offline") return "🔴";
+  if (s === "ready") return "✅";
+  if (s === "cloning") return "⏳";
+  if (s === "empty") return "⚪";
+  if (s === "error") return "❌";
+  return "⚪";
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * pi-factory-gate — AI Factory Orchestration Gate
+ *
+ * Tools: factory_list_agents, factory_get_agent, factory_create_job,
+ *        factory_get_job, factory_list_jobs, factory_stream_job,
+ *        factory_list_environments, factory_get_environment, factory_create_environment,
+ *        factory_list_workers, factory_list_workflows, factory_run_workflow,
+ *        factory_get_events, factory_status
+ * Config: .factoryrc.yml
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { listAgentsTool, getAgentTool } from "./tools/agents";
+import { createJobTool, getJobTool, listJobsTool, streamJobTool } from "./tools/jobs";
+import { listEnvironmentsTool, getEnvironmentTool, createEnvironmentTool } from "./tools/environments";
+import { listWorkersTool } from "./tools/workers";
+import { listWorkflowsTool, runWorkflowTool } from "./tools/workflows";
+import { getEventsTool, statusTool } from "./tools/events";
+
+export default function (pi: ExtensionAPI) {
+  // Agents
+  pi.registerTool(listAgentsTool);
+  pi.registerTool(getAgentTool);
+
+  // Jobs
+  pi.registerTool(createJobTool);
+  pi.registerTool(getJobTool);
+  pi.registerTool(listJobsTool);
+  pi.registerTool(streamJobTool);
+
+  // Environments
+  pi.registerTool(listEnvironmentsTool);
+  pi.registerTool(getEnvironmentTool);
+  pi.registerTool(createEnvironmentTool);
+
+  // Workers
+  pi.registerTool(listWorkersTool);
+
+  // Workflows
+  pi.registerTool(listWorkflowsTool);
+  pi.registerTool(runWorkflowTool);
+
+  // Events & Status
+  pi.registerTool(getEventsTool);
+  pi.registerTool(statusTool);
+}

package/src/tools/agents.ts

@@ -0,0 +1,119 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { factoryApi } from "../helpers";
+import type { AgentInfo, AgentDetail } from "../types";
+
+// ─── List Agents ───────────────────────────────────────────────────────────────
+
+export const listAgentsTool = {
+  name: "factory_list_agents" as const,
+  label: "List Factory Agents",
+  description:
+    "List all available AI agents in the wrok.in factory. Optionally filter by environment.",
+  parameters: Type.Object({
+    environment: Type.Optional(
+      Type.String({ description: "Filter agents by environment name" }),
+    ),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const qs = params.environment ? `?environment=${encodeURIComponent(params.environment)}` : "";
+    const r = await factoryApi<{ agents: AgentInfo[]; environment: string }>(
+      config,
+      `/agents${qs}`,
+    );
+
+    if (!r.ok || !r.data) {
+      return {
+        content: [{ type: "text", text: `❌ Failed to list agents: ${r.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const { agents } = r.data;
+    if (agents.length === 0) {
+      return {
+        content: [{ type: "text", text: "No agents registered." }],
+        details: { count: 0 },
+      };
+    }
+
+    const lines = [`🤖 Factory Agents (${agents.length})` + (params.environment ? ` in "${params.environment}"` : ""), ""];
+    for (const a of agents) {
+      const badge = a.enabled === false ? "🔴" : "🟢";
+      const tools = a.tools?.length ? ` [${a.tools.slice(0, 6).join(", ")}${a.tools.length > 6 ? ", ..." : ""}]` : "";
+      lines.push(`   ${badge} ${a.name}  source=${a.source}`);
+      lines.push(`        ${a.description || "(no description)"}${tools}`);
+      if (a.model && a.model !== "auto") {
+        lines.push(`        model: ${a.model}`);
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { count: agents.length, environment: params.environment || "default" },
+    };
+  },
+};
+
+// ─── Get Agent ─────────────────────────────────────────────────────────────────
+
+export const getAgentTool = {
+  name: "factory_get_agent" as const,
+  label: "Get Agent Detail",
+  description:
+    "Get detailed information about a specific factory agent, including its resolved configuration (inheritance, overrides).",
+  parameters: Type.Object({
+    name: Type.String({ description: "Agent name (e.g., 'code-reviewer', 'build-runner')" }),
+    environment: Type.Optional(
+      Type.String({ description: "Environment context for agent resolution" }),
+    ),
+  }),
+  async execute(_id: string, params: any, _s: any, _u: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const qs = params.environment ? `?environment=${encodeURIComponent(params.environment)}` : "";
+    const r = await factoryApi<AgentDetail>(
+      config,
+      `/agents/${encodeURIComponent(params.name)}${qs}`,
+    );
+
+    if (!r.ok) {
+      return {
+        content: [{ type: "text", text: `❌ Agent "${params.name}" not found: ${r.error || "unknown"}` }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const a = r.data!;
+    const lines = [
+      `🤖 ${a.name}`,
+      `   Description: ${a.description || "(none)"}`,
+      `   Source:      ${a.source}`,
+      `   Resolved:    ${a.resolvedFrom || "(direct)"}`,
+      `   Override:    ${a.isOverride ? "yes" : "no"}`,
+      `   Enabled:     ${a.enabled !== false ? "yes" : "no"}`,
+    ];
+
+    if (a.extends) lines.push(`   Extends:     ${a.extends}`);
+    if (a.model && a.model !== "auto") lines.push(`   Model:       ${a.model}`);
+    if (a.tools?.length) {
+      lines.push(`   Tools (${a.tools.length}):`);
+      for (const t of a.tools) lines.push(`      - ${t}`);
+    }
+    if (a.systemPrompt) {
+      const preview = a.systemPrompt.length > 300
+        ? a.systemPrompt.slice(0, 300) + "..."
+        : a.systemPrompt;
+      lines.push(`   System Prompt:`);
+      lines.push(`      ${preview}`);
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { name: a.name, source: a.source, resolvedFrom: a.resolvedFrom },
+    };
+  },
+};