pi-ultracode 0.1.0

package/src/workflow/agent-types.ts

@@ -0,0 +1,195 @@
+/**
+ * Custom agent types for workflow subagents.
+ *
+ * An agent type gives a subagent a distinct role: a system prompt, an optional
+ * tool allowlist, and optional model / thinking overrides. Types come from two
+ * places:
+ *   - Built-ins defined below (claude, Explore, Plan, general-purpose, code-reviewer).
+ *   - Markdown files with YAML-ish frontmatter discovered under:
+ *       <cwd>/.pi/ultracode/agents/*.md       (project)
+ *       ~/.pi/ultracode/agents/*.md           (user)
+ *       ~/.pi/agent/agents/*.md               (shared with other tools)
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ThinkingLevel } from "./agent-runner.ts";
+
+export interface AgentTypeDef {
+  name: string;
+  description: string;
+  /** Extra system guidance for this subagent. */
+  systemPrompt: string;
+  /** "append" (default) merges with the base coding prompt; "replace" is advisory only. */
+  systemPromptMode: "append" | "replace";
+  /** Optional allowlist of built-in tool names (read, bash, edit, write, grep, find, ls). */
+  tools?: string[];
+  /** Optional model pattern override. */
+  model?: string;
+  /** Optional thinking level override. */
+  thinking?: ThinkingLevel;
+  source: "builtin" | "user" | "project";
+}
+
+const BUILTIN_AGENT_TYPES: AgentTypeDef[] = [
+  {
+    name: "claude",
+    description: "General-purpose subagent with the full coding toolset.",
+    systemPrompt: "You are a capable, autonomous coding subagent. Complete the task end-to-end and report concrete results.",
+    systemPromptMode: "append",
+    source: "builtin",
+  },
+  {
+    name: "general-purpose",
+    description: "Research and multi-step execution with all tools.",
+    systemPrompt:
+      "You are a general-purpose research-and-execution subagent. Search broadly, follow leads across files, and return a thorough, well-organized answer with file:line references where relevant.",
+    systemPromptMode: "append",
+    source: "builtin",
+  },
+  {
+    name: "Explore",
+    description: "Read-only fan-out search. Locates code; does not modify it.",
+    systemPrompt:
+      "You are a read-only exploration subagent. Sweep many files/directories and report the conclusion with precise file:line references. Read excerpts rather than whole files. Do NOT modify anything.",
+    systemPromptMode: "append",
+    tools: ["read", "grep", "find", "ls", "bash"],
+    source: "builtin",
+  },
+  {
+    name: "Plan",
+    description: "Software architect. Designs an implementation plan; does not edit.",
+    systemPrompt:
+      "You are a software-architect subagent. Produce a concrete, step-by-step implementation plan: critical files, sequence, trade-offs, and risks. Do NOT modify files.",
+    systemPromptMode: "append",
+    tools: ["read", "grep", "find", "ls", "bash"],
+    source: "builtin",
+  },
+  {
+    name: "code-reviewer",
+    description: "Adversarial reviewer that hunts for correctness, security, and reliability defects.",
+    systemPrompt:
+      "You are an adversarial code-review subagent. Default to skepticism: try to REFUTE the claim or find the bug. Cite exact file:line evidence. If you cannot find a concrete defect, say so plainly rather than inventing one.",
+    systemPromptMode: "append",
+    source: "builtin",
+  },
+];
+
+const VALID_THINKING = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+export function discoverAgentTypes(cwd: string): Map<string, AgentTypeDef> {
+  const map = new Map<string, AgentTypeDef>();
+  for (const def of BUILTIN_AGENT_TYPES) map.set(def.name, def);
+
+  const dirs: Array<{ dir: string; source: AgentTypeDef["source"] }> = [
+    { dir: path.join(os.homedir(), ".pi", "agent", "agents"), source: "user" },
+    { dir: path.join(os.homedir(), ".pi", "ultracode", "agents"), source: "user" },
+    { dir: path.join(cwd, ".pi", "ultracode", "agents"), source: "project" },
+  ];
+
+  for (const { dir, source } of dirs) {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".md")) continue;
+      try {
+        const content = fs.readFileSync(path.join(dir, entry), "utf8");
+        const def = parseAgentTypeFile(content, entry.replace(/\.md$/, ""), source);
+        if (def) map.set(def.name, def); // project overrides user overrides builtin
+      } catch {
+        // ignore unreadable / malformed agent files
+      }
+    }
+  }
+  return map;
+}
+
+export function resolveAgentType(
+  agentType: string | undefined,
+  types: Map<string, AgentTypeDef>,
+): AgentTypeDef | undefined {
+  if (!agentType) return undefined;
+  const found = types.get(agentType);
+  if (found) return found;
+  // Case-insensitive fallback.
+  const lower = agentType.toLowerCase();
+  for (const def of types.values()) {
+    if (def.name.toLowerCase() === lower) return def;
+  }
+  return undefined;
+}
+
+export function parseAgentTypeFile(
+  content: string,
+  fallbackName: string,
+  source: AgentTypeDef["source"],
+): AgentTypeDef | undefined {
+  const { frontmatter, body } = parseFrontmatter(content);
+  const name = (frontmatter.name ?? fallbackName).trim();
+  if (!name) return undefined;
+  const tools = frontmatter.tools
+    ? frontmatter.tools
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean)
+    : undefined;
+  const thinking = frontmatter.thinking && VALID_THINKING.has(frontmatter.thinking.trim())
+    ? (frontmatter.thinking.trim() as ThinkingLevel)
+    : undefined;
+  const systemPromptMode = frontmatter.systemPromptMode === "replace" ? "replace" : "append";
+  const systemPrompt = (frontmatter.systemPrompt ?? body ?? "").trim();
+  return {
+    name,
+    description: (frontmatter.description ?? "").trim(),
+    systemPrompt,
+    systemPromptMode,
+    tools,
+    model: frontmatter.model?.trim() || undefined,
+    thinking,
+    source,
+  };
+}
+
+/**
+ * Minimal YAML-ish frontmatter parser: a leading `---` ... `---` block of
+ * `key: value` pairs, supporting block scalars (`key: |`).
+ */
+export function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: normalized };
+
+  const frontmatter: Record<string, string> = {};
+  const lines = match[1].split("\n");
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!kv) {
+      i++;
+      continue;
+    }
+    const key = kv[1];
+    let value = kv[2];
+    if (value === "|" || value === ">" || value === "|-" || value === ">-") {
+      // Block scalar: consume indented following lines.
+      const block: string[] = [];
+      i++;
+      while (i < lines.length && (lines[i].startsWith("  ") || lines[i].trim() === "")) {
+        block.push(lines[i].replace(/^ {2}/, ""));
+        i++;
+      }
+      frontmatter[key] = block.join("\n").trim();
+      continue;
+    }
+    value = value.trim().replace(/^["']|["']$/g, "");
+    frontmatter[key] = value;
+    i++;
+  }
+  return { frontmatter, body: match[2] ?? "" };
+}

package/src/workflow/display.ts

@@ -0,0 +1,245 @@
+/**
+ * Live progress snapshots for a running workflow, plus compact text renderers used
+ * for streamed tool updates and the final tool result.
+ */
+
+import type { WorkflowMeta } from "./parser.ts";
+
+export type WorkflowAgentStatus = "running" | "done" | "error" | "skipped" | "cached";
+
+export interface WorkflowAgentSnapshot {
+  id: number;
+  label: string;
+  phase?: string;
+  status: WorkflowAgentStatus;
+  resultPreview?: string;
+  error?: string;
+  /** Wall-clock ms when the agent started (host layer; set by the tool). */
+  startedAt?: number;
+  /** Wall-clock ms when the agent finished. */
+  endedAt?: number;
+  /** Runtime duration in ms (endedAt - startedAt). */
+  durationMs?: number;
+  /** Wall-clock ms of the last observed activity inside the subagent. */
+  lastActivityAt?: number;
+  /** Short activity label while running, e.g. "text", "bash", "thinking". */
+  activity?: string;
+  /** Ring buffer of recent text output while running (live, not persisted). */
+  streamTail?: string;
+}
+
+export interface WorkflowSnapshot {
+  runId?: string;
+  name: string;
+  description?: string;
+  phases: string[];
+  currentPhase?: string;
+  logs: string[];
+  agents: WorkflowAgentSnapshot[];
+  agentCount: number;
+  runningCount: number;
+  doneCount: number;
+  errorCount: number;
+  cachedCount: number;
+  spentTokens: number;
+  budgetTotal: number | null;
+  durationMs?: number;
+  result?: unknown;
+  status: "running" | "completed" | "aborted" | "failed";
+}
+
+export interface RenderOptions {
+  maxAgents?: number;
+  maxLogs?: number;
+  showResultPreviews?: boolean;
+  /** Show the live streaming tail under each running agent (inspect view). */
+  showStream?: boolean;
+  /** Override `Date.now()` for deterministic elapsed/idle rendering in tests. */
+  now?: number;
+}
+
+export function createSnapshot(meta: WorkflowMeta, runId: string, budgetTotal: number | null): WorkflowSnapshot {
+  return {
+    runId,
+    name: meta.name,
+    description: meta.description,
+    phases: meta.phases?.map((p) => p.title) ?? [],
+    logs: [],
+    agents: [],
+    agentCount: 0,
+    runningCount: 0,
+    doneCount: 0,
+    errorCount: 0,
+    cachedCount: 0,
+    spentTokens: 0,
+    budgetTotal,
+    status: "running",
+  };
+}
+
+export function recompute(snapshot: WorkflowSnapshot): WorkflowSnapshot {
+  const runningCount = snapshot.agents.filter((a) => a.status === "running").length;
+  const doneCount = snapshot.agents.filter((a) => a.status === "done" || a.status === "cached").length;
+  const errorCount = snapshot.agents.filter((a) => a.status === "error").length;
+  const cachedCount = snapshot.agents.filter((a) => a.status === "cached").length;
+  return { ...snapshot, agentCount: snapshot.agents.length, runningCount, doneCount, errorCount, cachedCount };
+}
+
+export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: RenderOptions = {}): string[] {
+  const maxAgents = options.maxAgents ?? 6;
+  const maxLogs = options.maxLogs ?? 2;
+  const showResultPreviews = options.showResultPreviews ?? false;
+  const showStream = options.showStream ?? false;
+  const now = options.now ?? Date.now();
+
+  const tokens = snapshot.spentTokens
+    ? ` · ${formatTokens(snapshot.spentTokens)}${snapshot.budgetTotal ? `/${formatTokens(snapshot.budgetTotal)}` : ""} tok`
+    : "";
+  const state =
+    snapshot.errorCount > 0
+      ? `, ${snapshot.errorCount} errors`
+      : snapshot.runningCount > 0
+        ? `, ${snapshot.runningCount} running`
+        : "";
+  const cached = snapshot.cachedCount ? ` · ${snapshot.cachedCount} cached` : "";
+  const header = `◆ ${statusMark(snapshot.status)} ${snapshot.name} (${snapshot.doneCount}/${snapshot.agentCount} done${state})${cached}${tokens}`;
+  const lines = [header];
+
+  const phaseNames = unique([
+    ...snapshot.phases,
+    ...(snapshot.currentPhase ? [snapshot.currentPhase] : []),
+    ...snapshot.agents.map((a) => a.phase).filter((p): p is string => Boolean(p)),
+  ]);
+  const rendered = new Set<WorkflowAgentSnapshot>();
+
+  for (const phase of phaseNames) {
+    const agents = snapshot.agents.filter((a) => a.phase === phase);
+    if (agents.length === 0 && snapshot.currentPhase !== phase) continue;
+    for (const a of agents) rendered.add(a);
+    const done = agents.filter((a) => a.status === "done" || a.status === "cached").length;
+    const running = agents.filter((a) => a.status === "running").length;
+    const errors = agents.filter((a) => a.status === "error").length;
+    const complete = agents.length > 0 && done + errors === agents.length;
+    const marker = running > 0 || (!complete && snapshot.currentPhase === phase) ? "▶" : complete ? "✓" : " ";
+    lines.push(
+      `  ${marker} ${phase} ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}`,
+    );
+    for (const agent of agents.slice(-maxAgents)) {
+      lines.push(renderAgentLine(agent, { showResultPreviews, showStream, now }));
+    }
+    if (agents.length > maxAgents) lines.push(`    … ${agents.length - maxAgents} earlier agents`);
+  }
+
+  const unphased = snapshot.agents.filter((a) => !rendered.has(a));
+  if (unphased.length) {
+    lines.push("  (unphased)");
+    for (const agent of unphased.slice(-maxAgents)) {
+      lines.push(renderAgentLine(agent, { showResultPreviews, showStream, now }));
+    }
+  }
+
+  for (const log of snapshot.logs.slice(-maxLogs)) lines.push(`  log: ${shorten(log, 100)}`);
+  return lines;
+}
+
+export function renderWorkflowText(snapshot: WorkflowSnapshot, options: RenderOptions = {}): string {
+  return renderWorkflowLines(snapshot, options).join("\n");
+}
+
+export function preview(value: unknown, max = 80): string {
+  const text = typeof value === "string" ? value : safeJson(value);
+  if (!text) return "";
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+
+function statusMark(status: WorkflowSnapshot["status"]): string {
+  switch (status) {
+    case "completed":
+      return "✓";
+    case "aborted":
+      return "■";
+    case "failed":
+      return "✗";
+    default:
+      return "▶";
+  }
+}
+
+function statusIcon(status: WorkflowAgentStatus): string {
+  switch (status) {
+    case "running":
+      return "●";
+    case "done":
+      return "✓";
+    case "cached":
+      return "⟲";
+    case "error":
+      return "✗";
+    case "skipped":
+      return "-";
+  }
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function shorten(value: string, max: number): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
+  return String(n);
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    return String(value);
+  }
+}
+
+/** Seconds of silence after which a running agent is flagged as idle. */
+export const IDLE_THRESHOLD_S = 30;
+
+function renderAgentLine(
+  agent: WorkflowAgentSnapshot,
+  opts: { showResultPreviews: boolean; showStream: boolean; now: number },
+): string {
+  const meta = agentMeta(agent, opts.now);
+  const result = opts.showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+  const stream =
+    opts.showStream && agent.status === "running" && agent.streamTail
+      ? `\n      ┊ ${shorten(agent.streamTail, 120)}`
+      : "";
+  return `    #${agent.id} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${meta}${result}${stream}`;
+}
+
+/** Compact per-agent timing/activity suffix for the live snapshot. */
+function agentMeta(agent: WorkflowAgentSnapshot, now: number): string {
+  if (agent.status === "running") {
+    const startedAt = agent.startedAt ?? now;
+    const elapsed = Math.max(0, Math.floor((now - startedAt) / 1000));
+    const lastAct = agent.lastActivityAt ?? startedAt;
+    const idle = Math.max(0, Math.floor((now - lastAct) / 1000));
+    if (idle >= IDLE_THRESHOLD_S) return ` · ${elapsed}s · ⚠ idle ${idle}s`;
+    const act = agent.activity ? ` · ${shorten(agent.activity, 20)}` : "";
+    return ` · ${elapsed}s${act}`;
+  }
+  if (agent.durationMs != null && agent.durationMs > 0) return ` · ${formatDuration(agent.durationMs)}`;
+  return "";
+}
+
+function formatDuration(ms: number): string {
+  const s = ms / 1000;
+  if (s < 1) return "<1s";
+  if (s < 60) return `${Math.round(s)}s`;
+  const m = Math.floor(s / 60);
+  const rem = Math.round(s % 60);
+  return `${m}m${rem ? ` ${rem}s` : ""}`;
+}

package/src/workflow/json-schema.ts

@@ -0,0 +1,116 @@
+/**
+ * Convert a plain JSON Schema (as written inside a workflow script's
+ * `agent(prompt, { schema })`) into a TypeBox `TSchema` so Pi can both validate
+ * the subagent's structured output and serialize a faithful tool schema to the model.
+ *
+ * Covers the common JSON Schema subset; anything unrecognized falls back to
+ * `Type.Unsafe`, which preserves the raw schema for the model without crashing.
+ */
+
+import { Type, type TSchema } from "typebox";
+
+type Json = Record<string, any>;
+
+export function jsonSchemaToTypeBox(schema: unknown): TSchema {
+  if (!schema || typeof schema !== "object") {
+    // No constraints -> accept anything.
+    return Type.Unsafe<unknown>({});
+  }
+  const node = schema as Json;
+  const annotations = pickAnnotations(node);
+
+  // Composite keywords first.
+  if (Array.isArray(node.enum)) {
+    const literals = node.enum.map((value: unknown) => Type.Literal(value as any));
+    return withAnnotations(literals.length === 1 ? literals[0] : Type.Union(literals), annotations);
+  }
+  if ("const" in node) {
+    return withAnnotations(Type.Literal(node.const), annotations);
+  }
+  if (Array.isArray(node.anyOf)) {
+    return withAnnotations(Type.Union(node.anyOf.map(jsonSchemaToTypeBox)), annotations);
+  }
+  if (Array.isArray(node.oneOf)) {
+    return withAnnotations(Type.Union(node.oneOf.map(jsonSchemaToTypeBox)), annotations);
+  }
+  if (Array.isArray(node.allOf)) {
+    return withAnnotations(Type.Intersect(node.allOf.map(jsonSchemaToTypeBox)), annotations);
+  }
+
+  const type = node.type;
+  if (Array.isArray(type)) {
+    // e.g. ["string", "null"]
+    return withAnnotations(
+      Type.Union(type.map((t: string) => jsonSchemaToTypeBox({ ...node, type: t, enum: undefined }))),
+      annotations,
+    );
+  }
+
+  switch (type) {
+    case "object":
+      return withAnnotations(objectSchema(node), annotations);
+    case "array":
+      return withAnnotations(arraySchema(node), annotations);
+    case "string":
+      return withAnnotations(Type.String(numericAndStringConstraints(node)), annotations);
+    case "number":
+      return withAnnotations(Type.Number(numericAndStringConstraints(node)), annotations);
+    case "integer":
+      return withAnnotations(Type.Integer(numericAndStringConstraints(node)), annotations);
+    case "boolean":
+      return withAnnotations(Type.Boolean(), annotations);
+    case "null":
+      return withAnnotations(Type.Null(), annotations);
+    default:
+      // Untyped object with properties is still an object.
+      if (node.properties) return withAnnotations(objectSchema(node), annotations);
+      if (node.items) return withAnnotations(arraySchema(node), annotations);
+      return Type.Unsafe<unknown>({ ...node });
+  }
+}
+
+function objectSchema(node: Json): TSchema {
+  const properties: Record<string, TSchema> = {};
+  const required: string[] = Array.isArray(node.required) ? node.required : [];
+  const props = (node.properties ?? {}) as Json;
+  for (const [key, value] of Object.entries(props)) {
+    const child = jsonSchemaToTypeBox(value);
+    properties[key] = required.includes(key) ? child : Type.Optional(child);
+  }
+  const options: Json = {};
+  if (node.additionalProperties === false) options.additionalProperties = false;
+  else if (node.additionalProperties && typeof node.additionalProperties === "object") {
+    options.additionalProperties = jsonSchemaToTypeBox(node.additionalProperties);
+  }
+  return Type.Object(properties, options);
+}
+
+function arraySchema(node: Json): TSchema {
+  const items = node.items ? jsonSchemaToTypeBox(Array.isArray(node.items) ? node.items[0] : node.items) : Type.Unknown();
+  const options: Json = {};
+  if (typeof node.minItems === "number") options.minItems = node.minItems;
+  if (typeof node.maxItems === "number") options.maxItems = node.maxItems;
+  if (node.uniqueItems === true) options.uniqueItems = true;
+  return Type.Array(items, options);
+}
+
+function numericAndStringConstraints(node: Json): Json {
+  const out: Json = {};
+  for (const key of ["minimum", "maximum", "minLength", "maxLength", "pattern", "format"]) {
+    if (node[key] !== undefined) out[key] = node[key];
+  }
+  return out;
+}
+
+function pickAnnotations(node: Json): Json {
+  const out: Json = {};
+  if (typeof node.description === "string") out.description = node.description;
+  if (typeof node.title === "string") out.title = node.title;
+  if (node.default !== undefined) out.default = node.default;
+  return out;
+}
+
+function withAnnotations(schema: TSchema, annotations: Json): TSchema {
+  if (Object.keys(annotations).length === 0) return schema;
+  return { ...schema, ...annotations } as TSchema;
+}