@kevin5251984/guild 0.2.18 → 0.2.20

package/src/tools.ts

@@ -7,6 +7,7 @@ import { Type, type Tool } from "@earendil-works/pi-ai";
 import { listHostSkills } from "./host-skills.ts";
 import type { McpToolRef } from "./mcp.ts";
 import {
+  defaultWorkspace,
   gateTool,
   parseSandbox,
   resolveToolPath,
@@ -75,8 +76,25 @@ export type ToolContext = {
     args: Record<string, unknown>,
     ctx: ToolContext,
   ) => Promise<ToolOutcome>;
+  /** Devin-style background spawn handles for this turn. Same Map across dispatch clones. */
+  spawnHandles?: Map<string, SpawnHandle>;
 };
 
+export type SpawnHandle = {
+  id: string;
+  title: string;
+  profile: string;
+  done: Promise<ToolOutcome>;
+  outcome?: ToolOutcome;
+  abort?: AbortController;
+};
+
+/** Pin the turn's handle Map before dispatch spreads a rest clone. */
+export function attachSpawnHandles(ctx: ToolContext): Map<string, SpawnHandle> {
+  if (!ctx.spawnHandles) ctx.spawnHandles = new Map();
+  return ctx.spawnHandles;
+}
+
 const BASE_TOOLS: Tool[] = [
   {
     name: "run",
@@ -169,7 +187,9 @@ export function guildTools(
       (tool) => tool.name === "read" || tool.name === "list",
     );
   } else if (sandbox === "workspace_write") {
-    tools = tools.filter((tool) => tool.name !== "image_gen");
+    tools = tools.filter(
+      (tool) => tool.name !== "image_gen" && tool.name !== "browser",
+    );
   }
   tools.push({
     name: "skill",
@@ -178,7 +198,7 @@ export function guildTools(
       name: Type.String({ description: "Skill name or slug" }),
     }),
   });
-  if ((ctx.spawnDepth ?? 0) < 1 && sandbox !== "read_only") {
+  if ((ctx.spawnDepth ?? 0) < 1) {
     const agents = ctx.subagents ?? [];
     const listed = agents
       .slice(0, 40)
@@ -190,14 +210,28 @@ export function guildTools(
     const catalog = listed ? ` Available: ${listed}.` : "";
     tools.push({
       name: "spawn",
-      description: `Spawn a subagent with a fresh context. It returns a summary, not a transcript. Use for parallel exploration, review, or a bounded implementation slice.${catalog} Subagents cannot spawn children.`,
+      description: `Delegate to a specialist (Devin run_subagent / Pi subagent / Codex spawn_agent). Fresh context; returns a summary, not a transcript. You stay coordinator. Single: title + task + profile (aliases: description/prompt, name/agent). Profiles: explorer (read-only survey), reviewer (read-only critique), worker (bounded patch). luna-explore maps to explorer, luna-general to worker. Independent surveys: background=true (is_background), then read_spawn with the agent_id before the final reply. Parallel: several spawn calls this round, or tasks: [{title, task, profile}, ...] (max 8, 4 at a time). Do not spawn for one known file or a one-line change.${catalog} A read_only parent still spawns; the child stays read_only. Subagents cannot spawn children.`,
       parameters: Type.Object({
-        prompt: Type.String({
-          description: "Self-contained task for the subagent. Include paths, constraints, and the deliverable.",
-        }),
+        prompt: Type.Optional(
+          Type.String({
+            description: "Self-contained task. Same as task.",
+          }),
+        ),
+        task: Type.Optional(
+          Type.String({ description: "Alias of prompt (Devin/Pi)" }),
+        ),
         name: Type.Optional(
           Type.String({
-            description: "Subagent name or slug from the library. Default worker.",
+            description: "Subagent name or slug. Default worker.",
+          }),
+        ),
+        agent: Type.Optional(
+          Type.String({ description: "Alias of name (Pi)" }),
+        ),
+        profile: Type.Optional(
+          Type.String({
+            description:
+              "Devin profile: explorer | reviewer | worker. luna-explore → explorer, luna-general → worker.",
           }),
         ),
         description: Type.Optional(
@@ -205,6 +239,51 @@ export function guildTools(
             description: "Short 3–8 word label for the chat UI",
           }),
         ),
+        title: Type.Optional(
+          Type.String({ description: "Alias of description (Devin title)" }),
+        ),
+        background: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, return agent_id immediately and keep working. Then call read_spawn.",
+          }),
+        ),
+        is_background: Type.Optional(
+          Type.Boolean({ description: "Alias of background (Devin)" }),
+        ),
+        tasks: Type.Optional(
+          Type.Array(
+            Type.Object({
+              prompt: Type.Optional(Type.String()),
+              task: Type.Optional(Type.String()),
+              name: Type.Optional(Type.String()),
+              agent: Type.Optional(Type.String()),
+              profile: Type.Optional(Type.String()),
+              description: Type.Optional(Type.String()),
+              title: Type.Optional(Type.String()),
+            }),
+            {
+              description:
+                "Pi parallel: run these subagents concurrently (max 8, 4 at a time).",
+            },
+          ),
+        ),
+      }),
+    });
+    tools.push({
+      name: "read_spawn",
+      description:
+        "Read a background spawn started with background=true (Devin read_subagent). Pass agent_id from spawn. block=true (default) waits; block=false returns running or the summary.",
+      parameters: Type.Object({
+        agent_id: Type.Optional(
+          Type.String({ description: "Id returned by background spawn" }),
+        ),
+        id: Type.Optional(Type.String({ description: "Alias of agent_id" })),
+        block: Type.Optional(
+          Type.Boolean({
+            description: "Wait for the child. Default true.",
+          }),
+        ),
       }),
     });
   }
@@ -222,7 +301,7 @@ export const GUILD_TOOLS: Tool[] = guildTools();
 
 function openaiParameters(name: string): {
   type: "object";
-  properties: Record<string, { type: "string"; description?: string }>;
+  properties: Record<string, unknown>;
   required: string[];
 } {
   if (name === "run") {
@@ -257,14 +336,42 @@ function openaiParameters(name: string): {
     };
   }
   if (name === "spawn") {
-    return {
+    const job = {
       type: "object",
       properties: {
-        prompt: { type: "string", description: "Self-contained task" },
+        prompt: { type: "string", description: "Self-contained task. Same as task." },
+        task: { type: "string", description: "Alias of prompt" },
         name: { type: "string", description: "Subagent name or slug" },
+        agent: { type: "string", description: "Alias of name" },
+        profile: { type: "string", description: "explorer | reviewer | worker" },
         description: { type: "string", description: "Short UI label" },
+        title: { type: "string", description: "Alias of description" },
       },
-      required: ["prompt"],
+    };
+    return {
+      type: "object",
+      properties: {
+        ...job.properties,
+        background: { type: "boolean", description: "Return agent_id immediately" },
+        is_background: { type: "boolean", description: "Alias of background" },
+        tasks: {
+          type: "array",
+          description: "Pi parallel: [{name, prompt}, ...] max 8, 4 at a time",
+          items: job,
+        },
+      },
+      required: [],
+    };
+  }
+  if (name === "read_spawn") {
+    return {
+      type: "object",
+      properties: {
+        agent_id: { type: "string", description: "Id from background spawn" },
+        id: { type: "string", description: "Alias of agent_id" },
+        block: { type: "boolean", description: "Wait. Default true." },
+      },
+      required: [],
     };
   }
   if (name === "image_gen") {
@@ -327,6 +434,7 @@ export const BUILTIN_TOOL_NAMES = [
   "list",
   "skill",
   "spawn",
+  "read_spawn",
   "image_gen",
   "browser",
 ] as const;
@@ -339,6 +447,7 @@ export async function executeTool(
   try {
     const refused = gateTool(name, args, ctx);
     if (refused) return refused;
+    attachSpawnHandles(ctx);
     if (ctx.dispatch) {
       const { dispatch, ...rest } = ctx;
       return await dispatch(name, args, rest);
@@ -359,9 +468,11 @@ export async function builtinExecute(
   ctx: ToolContext = {},
 ): Promise<ToolOutcome> {
   try {
+    // workspace_write resolves relative paths from the workspace root, which
+    // defaults to the guild checkout (same root gateTool checks against).
     const pathBase =
-      parseSandbox(ctx.sandbox) === "workspace_write" && ctx.workspace
-        ? resolveToolPath(ctx.workspace)
+      parseSandbox(ctx.sandbox) === "workspace_write"
+        ? resolveToolPath(ctx.workspace?.trim() || defaultWorkspace())
         : HOME;
     if (name === "run") {
       return await runCommand(
@@ -384,13 +495,12 @@ export async function builtinExecute(
     if (name === "list") return listDir(asString(args.path), pathBase);
     if (name === "skill") return loadSkill(asString(args.name), ctx.skills ?? []);
     if (name === "spawn") {
-      const { spawnSubagent } = await import("./subagent.ts");
-      return spawnSubagent({
-        prompt: asString(args.prompt),
-        name: typeof args.name === "string" ? args.name : "",
-        description: typeof args.description === "string" ? args.description : "",
-        ctx,
-      });
+      const { runSpawnJobs } = await import("./subagent.ts");
+      return runSpawnJobs(args, ctx);
+    }
+    if (name === "read_spawn") {
+      const { readSpawn } = await import("./subagent.ts");
+      return readSpawn(args, ctx);
     }
     if (name === "image_gen") {
       const { generateImage } = await import("./image-gen.ts");
@@ -713,7 +823,8 @@ Never say you cannot access this machine. Never tell the user to run the command
 When the question is about this computer, call tools first, then answer with evidence from the output.
 To generate an image, call image_gen with a prompt. Do not search the disk or load skills looking for Imagine. After it returns, include the markdown image in your reply.
 To use a real website in a browser, call browser with action=open and a url, then snapshot/click/type using refs like @e1. Default is a Hermes-shaped snapshot of the user's last_used Chrome profile (never the live profile). Set GUILD_BROWSER_REAL_PROFILE=0 for a throwaway empty profile.
-To delegate a bounded slice (explore, review, implement) to a specialist with its own context, call spawn. Pass a self-contained prompt. The subagent returns a summary. Subagents cannot spawn children.
+You stay coordinator. Spawn is the specialist, not a last resort (Devin run_subagent / Pi subagent / Codex spawn_agent). Call spawn for a survey (explorer / luna-explore), a critique (reviewer), or a bounded patch (worker / luna-general) instead of stuffing that work into this turn with list/read/run. Do not spawn for one known file or a one-line change. Independent surveys: spawn with background=true, keep working, then read_spawn {agent_id, block:true} before the final reply. Or several spawn calls / tasks: [{title, task, profile}] this round. Task must be self-contained (child has a fresh context). Do not let a child commit, push, or decide architecture. A read_only seat can still spawn; the child stays read_only. Subagents cannot spawn children.
+Independent tool calls in one round also run in parallel — fire several reads/searches together.
 Check the [exit code: N] marker on every run result; investigate failures before moving on. Prefer the workdir argument over cd.
 To follow a staffed skill, call skill with its exact name (or slug) before applying it. Relative paths in a skill resolve against that skill's base directory.
 Prefer small commands. macOS RAM: sysctl hw.memsize ; memory_pressure. Disk: df -h.`;

package/src/trajectory.ts

@@ -38,6 +38,49 @@ export function clip(text: string, n = CLIP): string {
   return one.slice(0, n - 1) + "…";
 }
 
+function recordOf(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+/** Old rows logged spawn as TOOL "spawn spawn". Present them as spawn. */
+export function promoteSpawnEvent<T extends { kind: string; summary: string; payload?: unknown }>(
+  event: T,
+): T & { kind: TrajectoryKind; summary: string } {
+  if (event.kind === "spawn") return event as T & { kind: TrajectoryKind; summary: string };
+  const payload = recordOf(event.payload);
+  const toolName = String(payload?.name || "");
+  const looksSpawn =
+    event.kind === "tool" &&
+    (toolName === "spawn" ||
+      toolName === "read_spawn" ||
+      /^\s*spawn(\s+spawn)?\s*$/i.test(event.summary || ""));
+  if (!looksSpawn) return event as T & { kind: TrajectoryKind; summary: string };
+  const args = recordOf(payload?.args) || payload || {};
+  if (toolName === "read_spawn") {
+    const waitId = String(args.agent_id || args.id || "").trim();
+    return {
+      ...event,
+      kind: "spawn",
+      summary: clip(`read ${waitId}`),
+    };
+  }
+  const agent = String(args.name || args.profile || "worker").trim() || "worker";
+  const label = String(args.title || args.description || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const prompt = String(args.prompt || args.task || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return {
+    ...event,
+    kind: "spawn",
+    summary: clip(
+      `${agent}${label ? " · " + label : ""}${prompt ? " — " + prompt : ""}`,
+    ),
+  };
+}
+
 function cap(value: unknown): unknown {
   if (typeof value === "string") {
     return value.length > FIELD_CAP ? value.slice(0, FIELD_CAP) : value;
@@ -140,17 +183,34 @@ export function turnTrajectoryEvents(input: {
       });
       continue;
     }
-    if (trace.name === "spawn") {
-      const agent = String(trace.args.name || "worker").trim() || "worker";
-      const label = String(trace.args.description || "").replace(/\s+/g, " ").trim();
-      const prompt = String(trace.args.prompt || "").replace(/\s+/g, " ").trim();
+    if (trace.name === "spawn" || trace.name === "read_spawn") {
+      const agent =
+        String(
+          trace.args.profile ||
+            trace.args.name ||
+            trace.args.agent ||
+            "worker",
+        ).trim() || "worker";
+      const label = String(trace.args.title || trace.args.description || "")
+        .replace(/\s+/g, " ")
+        .trim();
+      const prompt = String(trace.args.prompt || trace.args.task || "")
+        .replace(/\s+/g, " ")
+        .trim();
+      const bg =
+        trace.args.background === true || trace.args.is_background === true
+          ? " (bg)"
+          : "";
+      const waitId = String(trace.args.agent_id || trace.args.id || "").trim();
       events.push({
         ts,
         turnId,
         botId,
         kind: "spawn",
         summary: clip(
-          `${agent}${label ? " · " + label : ""}${prompt ? " — " + prompt : ""}${trace.running ? " …" : ""}`,
+          trace.name === "read_spawn"
+            ? `read ${waitId || agent}${trace.running ? " …" : ""}`
+            : `${agent}${bg}${label ? " · " + label : ""}${prompt ? " — " + prompt : ""}${trace.running ? " …" : ""}`,
         ),
         payload: cap(trace.args),
         result: String(cap(trace.text ?? "")),
@@ -261,16 +321,19 @@ export function synthesizeTrajectory(messages: ChatMessage[]): TrajectoryEvent[]
         continue;
       }
       if (part.type === "tool") {
+        const spawnish = part.name === "spawn" || part.name === "read_spawn";
         events.push({
           seq: seq++,
           ts,
           turnId,
           botId: msg.author,
-          kind: part.name === "spawn" ? "spawn" : "tool",
+          kind: spawnish ? "spawn" : "tool",
           summary: clip(
-            part.name === "spawn"
-              ? part.detail || part.label || "spawn"
-              : `${part.name} ${part.detail}`,
+            part.name === "read_spawn"
+              ? `read ${part.detail || ""}`
+              : part.name === "spawn"
+                ? part.detail || part.label || "spawn"
+                : `${part.name} ${part.detail}`,
           ),
           payload: { name: part.name, detail: part.detail },
           result: part.output,

package/src/usage.ts

@@ -59,13 +59,19 @@ export function fromOpenAiUsage(usage?: {
   prompt_tokens?: number;
   completion_tokens?: number;
   total_tokens?: number;
+  prompt_tokens_details?: { cached_tokens?: number };
+  input_tokens_details?: { cached_tokens?: number };
 } | null): ChatUsage {
   if (!usage) return { rounds: 1 };
   const input = num(usage.prompt_tokens);
   const output = num(usage.completion_tokens);
+  const cacheRead =
+    num(usage.prompt_tokens_details?.cached_tokens) ??
+    num(usage.input_tokens_details?.cached_tokens);
   return {
     input,
     output,
+    cacheRead,
     totalTokens: num(usage.total_tokens) || sum(input, output),
     rounds: 1,
   };
@@ -74,6 +80,8 @@ export function fromOpenAiUsage(usage?: {
 export function fromAnthropicUsage(usage?: {
   input_tokens?: number;
   output_tokens?: number;
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
 } | null): ChatUsage {
   if (!usage) return { rounds: 1 };
   const input = num(usage.input_tokens);
@@ -81,6 +89,8 @@ export function fromAnthropicUsage(usage?: {
   return {
     input,
     output,
+    cacheRead: num(usage.cache_read_input_tokens),
+    cacheWrite: num(usage.cache_creation_input_tokens),
     totalTokens: sum(input, output),
     rounds: 1,
   };

package/src/version.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Outbound User-Agent. npm ships this package's source, so the manifest always
+ * sits one level above `src/` — same lookup as `--version` in cli.ts.
+ */
+export function guildUserAgent(): string {
+  return `Guild/${guildVersion()}`;
+}
+
+let cached: string | null = null;
+
+export function guildVersion(): string {
+  if (cached !== null) return cached;
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ) as { version?: unknown };
+    const version = typeof pkg.version === "string" ? pkg.version.trim() : "";
+    cached = version || "0";
+  } catch {
+    cached = "0";
+  }
+  return cached;
+}

package/vendor/protocol/src/index.ts

@@ -37,6 +37,8 @@ export type Bot = {
   skillIds: string[];
   defaultPositionId: string;
   oneLiner?: string;
+  /** Public /generated/… sprite. Missing → procedural tavern buddy. */
+  portrait?: string;
   /** Chat model for this bot. Missing → guild default. */
   model?: ModelRef | null;
   createdAt: string;
@@ -53,6 +55,10 @@ export type Room = {
   name: string;
   memberIds: string[];
   createdAt: string;
+  /** Parent channel id when this is a branched side quest. */
+  parentId?: string;
+  /** Message id in the parent room that opened this branch. */
+  branchFromId?: string;
 };
 
 export type ChatPart =
@@ -114,6 +120,12 @@ export type ChatMessage = {
   steer?: boolean;
   /** Live bot this steer was aimed at. */
   steerBotId?: string;
+  /**
+   * Bot ids this message dispatches.
+   * User @mentions and bot handoffs. Missing on older rows (parse the body).
+   * Empty array means nobody — do not fall back to parsing.
+   */
+  mentions?: string[];
 };
 
 export type LlmApi =
@@ -121,9 +133,20 @@ export type LlmApi =
   | "anthropic-messages"
   | "openai-responses";
 
+export type ModelReasoning = {
+  /** Effort strings this model accepts, catalog order. Missing = no effort picker. */
+  supportedEfforts?: string[];
+  defaultEffort?: string;
+  /** When true, do not send `none` — reasoning cannot be turned off. */
+  mandatory?: boolean;
+  defaultEnabled?: boolean;
+  supportsMaxTokens?: boolean;
+};
+
 export type ModelEntry = {
   id: string;
   name?: string;
+  reasoning?: ModelReasoning;
 };
 
 export type ProviderEntry = {
@@ -141,11 +164,13 @@ export type AuxRole =
   | "skills"
   | "approval"
   | "title"
-  | "generate";
+  | "generate"
+  | "spawn";
 
 export type ModelsFile = {
   default?: ModelRef | null;
-  reasoning?: "minimal" | "low" | "medium" | "high";
+  /** Last chosen effort string (catalog-defined: low, high, xhigh, …). */
+  reasoning?: string;
   fast?: boolean;
   aux?: Partial<Record<AuxRole, ModelRef | null>>;
   recent?: ModelRef[];