@asterxsk/kiln 0.1.0 → 0.2.0

package/agent/extensions/subagents/src/prompt.ts

@@ -1,92 +1,92 @@
-/** All model-facing strings for the subagents tools. */
-
-/** Describes subagent_spawn, including harnesses and the fixed concurrency cap. */
-export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background subagent: a fully autonomous, headless agent with its own context window and the selected harness's normal host permissions. You choose the harness it runs on: pi (in-process pi session, inherits this environment's tools and config), claude (Claude Code), or codex (Codex CLI). Fire-and-forget: this returns immediately with an id. The subagent's final output is queued back to you as a message when it settles, or collect it explicitly with subagent_wait. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. Max 4 subagents can be running at once across all harnesses.";
-
-/** Adds background subagent delegation to the parent model's available-tools prompt. */
-export const SUBAGENT_SPAWN_PROMPT_SNIPPET =
-  "Spawn a background subagent on a chosen harness (pi, Claude Code, or Codex; own context, normal tools) for a self-contained task";
-
-/** Guides the parent model to delegate standalone tasks and avoid unnecessary blocking waits. */
-export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
-  "Use subagent_spawn to delegate self-contained tasks that can run in the background; give it a complete, standalone prompt.",
-  "Pick the subagent harness deliberately: pi unless you have a reason to prefer Claude Code or Codex (e.g. the user asked for one, or the task suits that harness).",
-  "After subagent_spawn, keep working; results arrive automatically. Only call subagent_wait when you cannot proceed without the result.",
-];
-
-/** Model-facing schema descriptions for subagent_spawn task and execution options. */
-export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
-  prompt:
-    "Task prompt for the subagent. Must be self-contained: include all needed context, file paths, and what to report back.",
-  name: "Short human-readable name for this subagent, shown in listings and the UI",
-  harness:
-    'Harness to run the subagent on: "pi" (in-process pi session; inherits this environment), "claude" (Claude Code), or "codex" (Codex CLI). Choose deliberately per task.',
-  workingDir:
-    "Trusted working directory for the autonomous child (default: current working directory)",
-  model:
-    'Model hint, interpreted by the chosen harness (pi: "provider/model-id" or model id; claude: model alias like "sonnet"/"opus"; codex: model slug). Omit for the harness default (pi inherits the current model).',
-  reasoningEffort:
-    "Reasoning effort on a shared scale; the harness maps it to its nearest native equivalent (pi thinking level, codex reasoning effort, claude thinking budget). Omit for the harness default (pi inherits the current level).",
-};
-
-/** Builds the subagent_spawn result that tells the parent model how to continue or inspect the child. */
-export function buildSubagentSpawnResult(options: {
-  id: string;
-  title: string;
-  harness: string;
-  modelLabel: string;
-  cwd: string;
-}) {
-  return (
-    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).\n` +
-    `It runs in the background. Its result will be delivered to you when it finishes, ` +
-    `or use subagent_wait(ids: ["${options.id}"]) to block for it, subagent_cancel to stop it, subagent_check to peek, subagent_list to see all.`
-  );
-}
-
-/** Describes explicit blocking collection of one or more subagent results. */
-export const SUBAGENT_WAIT_TOOL_DESCRIPTION =
-  "Block until all listed subagents have settled, then return their final outputs. Prefer letting results arrive automatically; use this only when you need a result before continuing.";
-
-/** Model-facing schema description for the subagent ids to await. */
-export const SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS = {
-  ids: 'Subagent ids to wait for, e.g. ["sa-1", "sa-2"]',
-};
-
-/** Describes aborting running subagents while retaining their partial transcripts. */
-export const SUBAGENT_CANCEL_TOOL_DESCRIPTION =
-  "Cancel one or more running subagents. This aborts their active work but preserves their partial session transcripts on disk.";
-
-/** Model-facing schema description for the subagent ids to cancel. */
-export const SUBAGENT_CANCEL_PARAMETER_DESCRIPTIONS = {
-  ids: 'Subagent ids to cancel, e.g. ["sa-1", "sa-2"]',
-};
-
-/** Describes nonblocking inspection of a subagent without consuming its result. */
-export const SUBAGENT_CHECK_TOOL_DESCRIPTION =
-  "Peek at a subagent's status and recent activity without blocking. Does not consume its result.";
-
-/** Model-facing schema description for the subagent id to inspect. */
-export const SUBAGENT_CHECK_PARAMETER_DESCRIPTIONS = {
-  id: "Subagent id",
-};
-
-/** Describes listing all tracked running and settled subagents. */
-export const SUBAGENT_LIST_TOOL_DESCRIPTION =
-  "List all subagents (running and finished) with their harness and status.";
-
-/** Builds the child completion/failure wrapper injected into the parent model's context. */
-export function buildSubagentResultMessage(options: {
-  id: string;
-  title: string;
-  status: "running" | "done" | "error";
-  errorText?: string;
-  output: string;
-}) {
-  const verb = options.status === "error" ? "failed" : "finished";
-  let text = `Subagent ${options.id} "${options.title}" ${verb}.`;
-  if (options.errorText) text += `\nError: ${options.errorText}`;
-  text += `\n\n${options.output}`;
-  return text;
-}
+/** All model-facing strings for the subagents tools. */
+
+/** Describes subagent_spawn, including harnesses and the fixed concurrency cap. */
+export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
+  "Spawn a background subagent: a fully autonomous, headless agent with its own context window and the selected harness's normal host permissions. You choose the harness it runs on: pi (in-process pi session, inherits this environment's tools and config), claude (Claude Code), or codex (Codex CLI). Fire-and-forget: this returns immediately with an id. The subagent's final output is queued back to you as a message when it settles, or collect it explicitly with subagent_wait. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. Max 4 subagents can be running at once across all harnesses.";
+
+/** Adds background subagent delegation to the parent model's available-tools prompt. */
+export const SUBAGENT_SPAWN_PROMPT_SNIPPET =
+  "Spawn a background subagent on a chosen harness (pi, Claude Code, or Codex; own context, normal tools) for a self-contained task";
+
+/** Guides the parent model to delegate standalone tasks and avoid unnecessary blocking waits. */
+export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
+  "Use subagent_spawn to delegate self-contained tasks that can run in the background; give it a complete, standalone prompt.",
+  "Pick the subagent harness deliberately: pi unless you have a reason to prefer Claude Code or Codex (e.g. the user asked for one, or the task suits that harness).",
+  "After subagent_spawn, keep working; results arrive automatically. Only call subagent_wait when you cannot proceed without the result.",
+];
+
+/** Model-facing schema descriptions for subagent_spawn task and execution options. */
+export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
+  prompt:
+    "Task prompt for the subagent. Must be self-contained: include all needed context, file paths, and what to report back.",
+  name: "Short human-readable name for this subagent, shown in listings and the UI",
+  harness:
+    'Harness to run the subagent on: "pi" (in-process pi session; inherits this environment), "claude" (Claude Code), or "codex" (Codex CLI). Choose deliberately per task.',
+  workingDir:
+    "Trusted working directory for the autonomous child (default: current working directory)",
+  model:
+    'Model hint, interpreted by the chosen harness (pi: "provider/model-id" or model id; claude: model alias like "sonnet"/"opus"; codex: model slug). Omit for the harness default (pi inherits the current model).',
+  reasoningEffort:
+    "Reasoning effort on a shared scale; the harness maps it to its nearest native equivalent (pi thinking level, codex reasoning effort, claude thinking budget). Omit for the harness default (pi inherits the current level).",
+};
+
+/** Builds the subagent_spawn result that tells the parent model how to continue or inspect the child. */
+export function buildSubagentSpawnResult(options: {
+  id: string;
+  title: string;
+  harness: string;
+  modelLabel: string;
+  cwd: string;
+}) {
+  return (
+    `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).\n` +
+    `It runs in the background. Its result will be delivered to you when it finishes, ` +
+    `or use subagent_wait(ids: ["${options.id}"]) to block for it, subagent_cancel to stop it, subagent_check to peek, subagent_list to see all.`
+  );
+}
+
+/** Describes explicit blocking collection of one or more subagent results. */
+export const SUBAGENT_WAIT_TOOL_DESCRIPTION =
+  "Block until all listed subagents have settled, then return their final outputs. Prefer letting results arrive automatically; use this only when you need a result before continuing.";
+
+/** Model-facing schema description for the subagent ids to await. */
+export const SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS = {
+  ids: 'Subagent ids to wait for, e.g. ["sa-1", "sa-2"]',
+};
+
+/** Describes aborting running subagents while retaining their partial transcripts. */
+export const SUBAGENT_CANCEL_TOOL_DESCRIPTION =
+  "Cancel one or more running subagents. This aborts their active work but preserves their partial session transcripts on disk.";
+
+/** Model-facing schema description for the subagent ids to cancel. */
+export const SUBAGENT_CANCEL_PARAMETER_DESCRIPTIONS = {
+  ids: 'Subagent ids to cancel, e.g. ["sa-1", "sa-2"]',
+};
+
+/** Describes nonblocking inspection of a subagent without consuming its result. */
+export const SUBAGENT_CHECK_TOOL_DESCRIPTION =
+  "Peek at a subagent's status and recent activity without blocking. Does not consume its result.";
+
+/** Model-facing schema description for the subagent id to inspect. */
+export const SUBAGENT_CHECK_PARAMETER_DESCRIPTIONS = {
+  id: "Subagent id",
+};
+
+/** Describes listing all tracked running and settled subagents. */
+export const SUBAGENT_LIST_TOOL_DESCRIPTION =
+  "List all subagents (running and finished) with their harness and status.";
+
+/** Builds the child completion/failure wrapper injected into the parent model's context. */
+export function buildSubagentResultMessage(options: {
+  id: string;
+  title: string;
+  status: "running" | "done" | "error";
+  errorText?: string;
+  output: string;
+}) {
+  const verb = options.status === "error" ? "failed" : "finished";
+  let text = `Subagent ${options.id} "${options.title}" ${verb}.`;
+  if (options.errorText) text += `\nError: ${options.errorText}`;
+  text += `\n\n${options.output}`;
+  return text;
+}

package/agent/extensions/subagents/src/result-delivery.ts

@@ -1,20 +1,20 @@
-export function createDeferredResultDelivery<T extends { id: string }>() {
-  const pending = new Map<string, T>();
-
-  return {
-    defer(result: T) {
-      pending.set(result.id, result);
-    },
-    consume(ids: Iterable<string>) {
-      for (const id of ids) pending.delete(id);
-    },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
-      return results;
-    },
-    clear() {
-      pending.clear();
-    },
-  };
-}
+export function createDeferredResultDelivery<T extends { id: string }>() {
+  const pending = new Map<string, T>();
+
+  return {
+    defer(result: T) {
+      pending.set(result.id, result);
+    },
+    consume(ids: Iterable<string>) {
+      for (const id of ids) pending.delete(id);
+    },
+    drain() {
+      const results = [...pending.values()];
+      pending.clear();
+      return results;
+    },
+    clear() {
+      pending.clear();
+    },
+  };
+}

package/agent/extensions/subagents/src/runtime.ts

@@ -1,53 +1,53 @@
-/**
- * Layer composition and the async entry-point boundary.
- *
- * Everything inside the extension is Effect generators; this module is where
- * tool handlers (plain async functions) run those effects against one shared
- * ManagedRuntime.
- */
-
-import { Cause, Exit, Layer, ManagedRuntime, type Effect } from "effect";
-import { BackendRegistry, type SubagentBackend } from "./backend.ts";
-import { claudeBackend } from "./backends/claude.ts";
-import { codexBackend } from "./backends/codex.ts";
-import { piBackend } from "./backends/pi.ts";
-import type { BackendName } from "./domain.ts";
-
-const BackendRegistryLive = Layer.sync(BackendRegistry, () => {
-  const backends: SubagentBackend[] = [piBackend, claudeBackend, codexBackend];
-  return new Map<BackendName, SubagentBackend>(
-    backends.map((backend) => [backend.name, backend]),
-  );
-});
-
-import { SubagentManagerLive } from "./manager.ts";
-
-const AppLayer = SubagentManagerLive.pipe(Layer.provide(BackendRegistryLive));
-
-export function createSubagentRuntime() {
-  return ManagedRuntime.make(AppLayer);
-}
-
-export type SubagentRuntime = ReturnType<typeof createSubagentRuntime>;
-
-/**
- * Run an effect from an async tool handler. Typed failures and defects are
- * converted to thrown Errors (what pi's tool contract expects); interruption
- * (tool AbortSignal) throws `interruptMessage`.
- */
-export async function runTool<A, E>(
-  runtime: SubagentRuntime,
-  effect: Effect.Effect<A, E>,
-  options: { signal?: AbortSignal; interruptMessage?: string } = {},
-) {
-  const exit = await runtime.runPromiseExit(
-    effect,
-    options.signal ? { signal: options.signal } : undefined,
-  );
-  if (Exit.isSuccess(exit)) return exit.value;
-  if (Cause.hasInterruptsOnly(exit.cause)) {
-    throw new Error(options.interruptMessage ?? "Operation was aborted.");
-  }
-  const [first] = Cause.prettyErrors(exit.cause);
-  throw new Error(first?.message ?? Cause.pretty(exit.cause));
-}
+/**
+ * Layer composition and the async entry-point boundary.
+ *
+ * Everything inside the extension is Effect generators; this module is where
+ * tool handlers (plain async functions) run those effects against one shared
+ * ManagedRuntime.
+ */
+
+import { Cause, Exit, Layer, ManagedRuntime, type Effect } from "effect";
+import { BackendRegistry, type SubagentBackend } from "./backend.ts";
+import { claudeBackend } from "./backends/claude.ts";
+import { codexBackend } from "./backends/codex.ts";
+import { piBackend } from "./backends/pi.ts";
+import type { BackendName } from "./domain.ts";
+
+const BackendRegistryLive = Layer.sync(BackendRegistry, () => {
+  const backends: SubagentBackend[] = [piBackend, claudeBackend, codexBackend];
+  return new Map<BackendName, SubagentBackend>(
+    backends.map((backend) => [backend.name, backend]),
+  );
+});
+
+import { SubagentManagerLive } from "./manager.ts";
+
+const AppLayer = SubagentManagerLive.pipe(Layer.provide(BackendRegistryLive));
+
+export function createSubagentRuntime() {
+  return ManagedRuntime.make(AppLayer);
+}
+
+export type SubagentRuntime = ReturnType<typeof createSubagentRuntime>;
+
+/**
+ * Run an effect from an async tool handler. Typed failures and defects are
+ * converted to thrown Errors (what pi's tool contract expects); interruption
+ * (tool AbortSignal) throws `interruptMessage`.
+ */
+export async function runTool<A, E>(
+  runtime: SubagentRuntime,
+  effect: Effect.Effect<A, E>,
+  options: { signal?: AbortSignal; interruptMessage?: string } = {},
+) {
+  const exit = await runtime.runPromiseExit(
+    effect,
+    options.signal ? { signal: options.signal } : undefined,
+  );
+  if (Exit.isSuccess(exit)) return exit.value;
+  if (Cause.hasInterruptsOnly(exit.cause)) {
+    throw new Error(options.interruptMessage ?? "Operation was aborted.");
+  }
+  const [first] = Cause.prettyErrors(exit.cause);
+  throw new Error(first?.message ?? Cause.pretty(exit.cause));
+}