@asterxsk/kiln 0.1.0 → 0.3.0

package/agent.bak.20260905-190020/extensions/subagents/src/prompt.ts

@@ -0,0 +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;
+}

package/agent.bak.20260905-190020/extensions/subagents/src/result-delivery.ts

@@ -0,0 +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();
+    },
+  };
+}

package/agent.bak.20260905-190020/extensions/subagents/src/runtime.ts

@@ -0,0 +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));
+}