@asterxsk/kiln 0.1.0 → 0.3.0

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

@@ -1,253 +1,253 @@
-/**
- * Domain model for subagents.
- *
- * Everything downstream of a backend (manager, tools, UI) speaks only these
- * types. Backends translate their native streams (pi session events, Claude
- * Agent SDK messages, Codex app-server JSON-RPC notifications) into the
- * normalized `SubagentEvent` union.
- */
-
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { Data } from "effect";
-
-export const BACKEND_NAMES = ["pi", "claude", "codex"] as const;
-export type BackendName = (typeof BACKEND_NAMES)[number];
-
-/** Who initiated the session. User asides stay out of model-facing tooling. */
-export type SubagentOrigin = "model" | "btw";
-
-/**
- * Shared reasoning-effort scale (pi's thinking levels). Each backend maps a
- * value to its nearest native equivalent: pi uses it directly, codex
- * translates to its reasoning-effort slugs, claude translates to thinking
- * budgets. Omitted = backend default (pi inherits the parent level).
- */
-export const REASONING_EFFORTS = [
-  "off",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-] as const;
-export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
-
-export type SubagentStatus = "running" | "done" | "error";
-
-/** Parent-session context resolved by the tool layer and passed opaquely. */
-export interface ParentContext {
-  readonly parentCwd: string;
-  readonly projectTrusted: boolean;
-  /** Parent pi model, for the pi backend's "inherit" default. */
-  readonly inheritedModel?: { readonly provider: string; readonly id: string };
-  readonly inheritedThinkingLevel?: string;
-  /** Parent model registry; required by the pi backend to resolve models. */
-  readonly modelRegistry?: ModelRegistry;
-}
-
-export interface SpawnTask {
-  /** Omitted for normal tool-driven spawns. */
-  readonly origin?: SubagentOrigin;
-  readonly prompt: string;
-  readonly title: string;
-  readonly cwd: string;
-  /**
-   * Generic model hint, interpreted per backend:
-   * pi: "provider/model-id" or bare model id; claude: model alias;
-   * codex: model slug. Omitted = backend default / inherit.
-   */
-  readonly model?: string;
-  /** Shared effort scale; each backend maps it to its native equivalent. */
-  readonly reasoningEffort?: ReasoningEffort;
-  readonly parent: ParentContext;
-}
-
-export interface SubagentMeta {
-  readonly backend: BackendName;
-  /** Display label, e.g. "anthropic/claude-opus-4-5" or "gpt-5-codex". */
-  readonly modelLabel?: string;
-  /** Context window capacity for utilization display, when known. */
-  readonly contextWindow?: number;
-  /** pi session file / Claude projects JSONL / Codex rollout path. */
-  readonly sessionFilePath?: string;
-  /** Claude session id / Codex conversation id. */
-  readonly nativeSessionId?: string;
-}
-
-// --- Transcript ------------------------------------------------------------
-
-export type TranscriptPart =
-  | { readonly type: "text"; readonly text: string }
-  | {
-      readonly type: "thinking";
-      readonly text: string;
-      readonly redacted?: boolean;
-    }
-  | {
-      readonly type: "toolCall";
-      readonly toolId: string;
-      readonly name: string;
-      readonly argsPreview?: string;
-    };
-
-export type TranscriptItem =
-  | { readonly kind: "user"; readonly text: string }
-  | {
-      readonly kind: "assistant";
-      readonly parts: ReadonlyArray<TranscriptPart>;
-    }
-  | {
-      readonly kind: "toolResult";
-      readonly toolId: string;
-      readonly name: string;
-      readonly isError: boolean;
-      readonly outputPreview?: string;
-    };
-
-export interface LiveToolState {
-  readonly toolId: string;
-  readonly name: string;
-  readonly argsPreview?: string;
-  readonly outputPreview?: string;
-  readonly done?: boolean;
-  readonly isError?: boolean;
-}
-
-export interface QueuedMessage {
-  readonly text: string;
-  readonly kind: "steer" | "follow-up";
-}
-
-// --- Events ------------------------------------------------------------------
-
-export type RunOutcome =
-  | { readonly _tag: "Completed"; readonly finalText: string }
-  | {
-      readonly _tag: "Failed";
-      readonly errorText: string;
-      readonly partialText?: string;
-    }
-  | { readonly _tag: "Interrupted"; readonly partialText?: string };
-
-/**
- * Normalized activity stream. Previews (`argsPreview`, `outputPreview`) are
- * pre-flattened single-line strings because the UI only ever renders one
- * sanitized line, which keeps three different native tool-result shapes out
- * of the interface.
- */
-export type SubagentEvent =
-  // lifecycle (a session can run multiple turns via send())
-  | { readonly _tag: "RunStarted" }
-  | { readonly _tag: "RunSettled"; readonly outcome: RunOutcome }
-  // transcript building blocks
-  | { readonly _tag: "UserMessage"; readonly text: string }
-  | {
-      readonly _tag: "AssistantDelta";
-      readonly kind: "text" | "thinking";
-      readonly delta: string;
-    }
-  | {
-      readonly _tag: "AssistantMessage";
-      readonly parts: ReadonlyArray<TranscriptPart>;
-    }
-  | {
-      readonly _tag: "ToolStart";
-      readonly toolId: string;
-      readonly name: string;
-      readonly argsPreview?: string;
-    }
-  | {
-      readonly _tag: "ToolUpdate";
-      readonly toolId: string;
-      readonly outputPreview?: string;
-    }
-  | {
-      readonly _tag: "ToolEnd";
-      readonly toolId: string;
-      readonly name: string;
-      readonly isError: boolean;
-      readonly outputPreview?: string;
-    }
-  // bookkeeping
-  | {
-      readonly _tag: "QueueChanged";
-      readonly queued: ReadonlyArray<QueuedMessage>;
-    }
-  | {
-      readonly _tag: "UsageChanged";
-      readonly tokens?: number;
-      readonly contextWindow?: number;
-    }
-  | { readonly _tag: "MetaChanged"; readonly meta: Partial<SubagentMeta> }
-  /** Non-fatal diagnostics. Fatal failures arrive as a RunSettled outcome. */
-  | { readonly _tag: "BackendError"; readonly message: string };
-
-// --- Snapshot ---------------------------------------------------------------
-
-/**
- * The manager folds `SubagentEvent`s into one snapshot per subagent. This is
- * everything the tools, footer status, and both TUI views read.
- */
-export interface SubagentSnapshot {
-  readonly id: string;
-  readonly origin: SubagentOrigin;
-  readonly backend: BackendName;
-  readonly title: string;
-  readonly prompt: string;
-  readonly cwd: string;
-  readonly status: SubagentStatus;
-  readonly createdAt: number;
-  readonly settledAt?: number;
-  readonly errorText?: string;
-  readonly meta: SubagentMeta;
-  readonly usage: { readonly tokens?: number; readonly contextWindow?: number };
-  readonly transcript: ReadonlyArray<TranscriptItem>;
-  /** Streaming assistant buffers, cleared when the finalized message lands. */
-  readonly liveAssistant?: { readonly text: string; readonly thinking: string };
-  readonly liveTools: ReadonlyArray<LiveToolState>;
-  readonly queued: ReadonlyArray<QueuedMessage>;
-  /** Final text of the most recent completed run (v1 `finalOutput`). */
-  readonly finalText: string;
-  /** Count of finalized assistant messages (for subagent_check). */
-  readonly turns: number;
-}
-
-/** Final text, or the live streaming buffer while a run is active (v1 `latestOutput`). */
-export function latestText(snap: SubagentSnapshot) {
-  const live = snap.liveAssistant?.text.trim();
-  if (live) return live;
-  return snap.finalText;
-}
-
-export function formatElapsed(snap: SubagentSnapshot) {
-  const end = snap.settledAt ?? Date.now();
-  const totalSeconds = Math.max(0, Math.round((end - snap.createdAt) / 1000));
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  return minutes > 0
-    ? `${minutes}m${seconds.toString().padStart(2, "0")}s`
-    : `${seconds}s`;
-}
-
-// --- Errors -------------------------------------------------------------------
-
-export class SpawnError extends Data.TaggedError("SpawnError")<{
-  readonly message: string;
-}> {}
-
-export class BackendUnavailableError extends Data.TaggedError(
-  "BackendUnavailableError",
-)<{
-  readonly message: string;
-}> {}
-
-export class ConcurrencyLimitError extends Data.TaggedError(
-  "ConcurrencyLimitError",
-)<{
-  readonly message: string;
-}> {}
-
-export class SendError extends Data.TaggedError("SendError")<{
-  readonly message: string;
-}> {}
+/**
+ * Domain model for subagents.
+ *
+ * Everything downstream of a backend (manager, tools, UI) speaks only these
+ * types. Backends translate their native streams (pi session events, Claude
+ * Agent SDK messages, Codex app-server JSON-RPC notifications) into the
+ * normalized `SubagentEvent` union.
+ */
+
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { Data } from "effect";
+
+export const BACKEND_NAMES = ["pi", "claude", "codex"] as const;
+export type BackendName = (typeof BACKEND_NAMES)[number];
+
+/** Who initiated the session. User asides stay out of model-facing tooling. */
+export type SubagentOrigin = "model" | "btw";
+
+/**
+ * Shared reasoning-effort scale (pi's thinking levels). Each backend maps a
+ * value to its nearest native equivalent: pi uses it directly, codex
+ * translates to its reasoning-effort slugs, claude translates to thinking
+ * budgets. Omitted = backend default (pi inherits the parent level).
+ */
+export const REASONING_EFFORTS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+
+export type SubagentStatus = "running" | "done" | "error";
+
+/** Parent-session context resolved by the tool layer and passed opaquely. */
+export interface ParentContext {
+  readonly parentCwd: string;
+  readonly projectTrusted: boolean;
+  /** Parent pi model, for the pi backend's "inherit" default. */
+  readonly inheritedModel?: { readonly provider: string; readonly id: string };
+  readonly inheritedThinkingLevel?: string;
+  /** Parent model registry; required by the pi backend to resolve models. */
+  readonly modelRegistry?: ModelRegistry;
+}
+
+export interface SpawnTask {
+  /** Omitted for normal tool-driven spawns. */
+  readonly origin?: SubagentOrigin;
+  readonly prompt: string;
+  readonly title: string;
+  readonly cwd: string;
+  /**
+   * Generic model hint, interpreted per backend:
+   * pi: "provider/model-id" or bare model id; claude: model alias;
+   * codex: model slug. Omitted = backend default / inherit.
+   */
+  readonly model?: string;
+  /** Shared effort scale; each backend maps it to its native equivalent. */
+  readonly reasoningEffort?: ReasoningEffort;
+  readonly parent: ParentContext;
+}
+
+export interface SubagentMeta {
+  readonly backend: BackendName;
+  /** Display label, e.g. "anthropic/claude-opus-4-5" or "gpt-5-codex". */
+  readonly modelLabel?: string;
+  /** Context window capacity for utilization display, when known. */
+  readonly contextWindow?: number;
+  /** pi session file / Claude projects JSONL / Codex rollout path. */
+  readonly sessionFilePath?: string;
+  /** Claude session id / Codex conversation id. */
+  readonly nativeSessionId?: string;
+}
+
+// --- Transcript ------------------------------------------------------------
+
+export type TranscriptPart =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "thinking";
+      readonly text: string;
+      readonly redacted?: boolean;
+    }
+  | {
+      readonly type: "toolCall";
+      readonly toolId: string;
+      readonly name: string;
+      readonly argsPreview?: string;
+    };
+
+export type TranscriptItem =
+  | { readonly kind: "user"; readonly text: string }
+  | {
+      readonly kind: "assistant";
+      readonly parts: ReadonlyArray<TranscriptPart>;
+    }
+  | {
+      readonly kind: "toolResult";
+      readonly toolId: string;
+      readonly name: string;
+      readonly isError: boolean;
+      readonly outputPreview?: string;
+    };
+
+export interface LiveToolState {
+  readonly toolId: string;
+  readonly name: string;
+  readonly argsPreview?: string;
+  readonly outputPreview?: string;
+  readonly done?: boolean;
+  readonly isError?: boolean;
+}
+
+export interface QueuedMessage {
+  readonly text: string;
+  readonly kind: "steer" | "follow-up";
+}
+
+// --- Events ------------------------------------------------------------------
+
+export type RunOutcome =
+  | { readonly _tag: "Completed"; readonly finalText: string }
+  | {
+      readonly _tag: "Failed";
+      readonly errorText: string;
+      readonly partialText?: string;
+    }
+  | { readonly _tag: "Interrupted"; readonly partialText?: string };
+
+/**
+ * Normalized activity stream. Previews (`argsPreview`, `outputPreview`) are
+ * pre-flattened single-line strings because the UI only ever renders one
+ * sanitized line, which keeps three different native tool-result shapes out
+ * of the interface.
+ */
+export type SubagentEvent =
+  // lifecycle (a session can run multiple turns via send())
+  | { readonly _tag: "RunStarted" }
+  | { readonly _tag: "RunSettled"; readonly outcome: RunOutcome }
+  // transcript building blocks
+  | { readonly _tag: "UserMessage"; readonly text: string }
+  | {
+      readonly _tag: "AssistantDelta";
+      readonly kind: "text" | "thinking";
+      readonly delta: string;
+    }
+  | {
+      readonly _tag: "AssistantMessage";
+      readonly parts: ReadonlyArray<TranscriptPart>;
+    }
+  | {
+      readonly _tag: "ToolStart";
+      readonly toolId: string;
+      readonly name: string;
+      readonly argsPreview?: string;
+    }
+  | {
+      readonly _tag: "ToolUpdate";
+      readonly toolId: string;
+      readonly outputPreview?: string;
+    }
+  | {
+      readonly _tag: "ToolEnd";
+      readonly toolId: string;
+      readonly name: string;
+      readonly isError: boolean;
+      readonly outputPreview?: string;
+    }
+  // bookkeeping
+  | {
+      readonly _tag: "QueueChanged";
+      readonly queued: ReadonlyArray<QueuedMessage>;
+    }
+  | {
+      readonly _tag: "UsageChanged";
+      readonly tokens?: number;
+      readonly contextWindow?: number;
+    }
+  | { readonly _tag: "MetaChanged"; readonly meta: Partial<SubagentMeta> }
+  /** Non-fatal diagnostics. Fatal failures arrive as a RunSettled outcome. */
+  | { readonly _tag: "BackendError"; readonly message: string };
+
+// --- Snapshot ---------------------------------------------------------------
+
+/**
+ * The manager folds `SubagentEvent`s into one snapshot per subagent. This is
+ * everything the tools, footer status, and both TUI views read.
+ */
+export interface SubagentSnapshot {
+  readonly id: string;
+  readonly origin: SubagentOrigin;
+  readonly backend: BackendName;
+  readonly title: string;
+  readonly prompt: string;
+  readonly cwd: string;
+  readonly status: SubagentStatus;
+  readonly createdAt: number;
+  readonly settledAt?: number;
+  readonly errorText?: string;
+  readonly meta: SubagentMeta;
+  readonly usage: { readonly tokens?: number; readonly contextWindow?: number };
+  readonly transcript: ReadonlyArray<TranscriptItem>;
+  /** Streaming assistant buffers, cleared when the finalized message lands. */
+  readonly liveAssistant?: { readonly text: string; readonly thinking: string };
+  readonly liveTools: ReadonlyArray<LiveToolState>;
+  readonly queued: ReadonlyArray<QueuedMessage>;
+  /** Final text of the most recent completed run (v1 `finalOutput`). */
+  readonly finalText: string;
+  /** Count of finalized assistant messages (for subagent_check). */
+  readonly turns: number;
+}
+
+/** Final text, or the live streaming buffer while a run is active (v1 `latestOutput`). */
+export function latestText(snap: SubagentSnapshot) {
+  const live = snap.liveAssistant?.text.trim();
+  if (live) return live;
+  return snap.finalText;
+}
+
+export function formatElapsed(snap: SubagentSnapshot) {
+  const end = snap.settledAt ?? Date.now();
+  const totalSeconds = Math.max(0, Math.round((end - snap.createdAt) / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0
+    ? `${minutes}m${seconds.toString().padStart(2, "0")}s`
+    : `${seconds}s`;
+}
+
+// --- Errors -------------------------------------------------------------------
+
+export class SpawnError extends Data.TaggedError("SpawnError")<{
+  readonly message: string;
+}> {}
+
+export class BackendUnavailableError extends Data.TaggedError(
+  "BackendUnavailableError",
+)<{
+  readonly message: string;
+}> {}
+
+export class ConcurrencyLimitError extends Data.TaggedError(
+  "ConcurrencyLimitError",
+)<{
+  readonly message: string;
+}> {}
+
+export class SendError extends Data.TaggedError("SendError")<{
+  readonly message: string;
+}> {}

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

@@ -1,74 +1,74 @@
-/**
- * Formatting helpers (self-contained copies of the v1 shared helpers:
- * context-utilization + activity-status).
- */
-
-import type { Theme } from "@earendil-works/pi-coding-agent";
-
-export interface ContextUtilization {
-  /** Current conversation context occupancy; undefined while unknown. */
-  tokens?: number | null;
-  /** Capacity of the model currently serving the conversation. */
-  contextWindow?: number | null;
-}
-
-function usableTokens(value: number | null | undefined) {
-  return typeof value === "number" && Number.isFinite(value) && value >= 0
-    ? value
-    : undefined;
-}
-
-function usableCapacity(value: number | null | undefined) {
-  return typeof value === "number" && Number.isFinite(value) && value > 0
-    ? value
-    : undefined;
-}
-
-export function contextPercent(usage: ContextUtilization) {
-  const tokens = usableTokens(usage.tokens);
-  const capacity = usableCapacity(usage.contextWindow);
-  if (tokens === undefined || capacity === undefined) return undefined;
-  return Math.round(Math.min(100, Math.max(0, (tokens / capacity) * 100)));
-}
-
-export function formatCompactTokens(count: number) {
-  if (count < 1000) return Math.round(count).toString();
-  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
-  if (count < 1000000) return `${Math.round(count / 1000)}k`;
-  return `${(count / 1000000).toFixed(1)}M`;
-}
-
-/**
- * Render `%/capacity`. If occupancy is unknown, retain the useful capacity
- * as `?%/capacity`; with no valid capacity, omit the statistic entirely.
- */
-export function formatContextUtilization(usage: ContextUtilization) {
-  const capacity = usableCapacity(usage.contextWindow);
-  if (capacity === undefined) return "";
-  const percent = contextPercent(usage);
-  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
-}
-
-interface ActivityCounts {
-  running: number;
-  done: number;
-  failed: number;
-}
-
-const SQUARE = "■";
-
-export function formatActivityStatus(theme: Theme, counts: ActivityCounts) {
-  const parts: string[] = [];
-  if (counts.running > 0) {
-    parts.push(theme.fg("warning", `${SQUARE} ${counts.running} running`));
-  }
-  if (counts.done > 0) {
-    parts.push(theme.fg("success", `${SQUARE} ${counts.done} done`));
-  }
-  if (counts.failed > 0) {
-    parts.push(theme.fg("error", `${SQUARE} ${counts.failed} failed`));
-  }
-  parts.push(theme.fg("accent", "/subagents") + theme.fg("dim", " to view"));
-
-  return `${theme.fg("muted", "subagents:")} ${parts.join(theme.fg("dim", " · "))}`;
-}
+/**
+ * Formatting helpers (self-contained copies of the v1 shared helpers:
+ * context-utilization + activity-status).
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+export interface ContextUtilization {
+  /** Current conversation context occupancy; undefined while unknown. */
+  tokens?: number | null;
+  /** Capacity of the model currently serving the conversation. */
+  contextWindow?: number | null;
+}
+
+function usableTokens(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : undefined;
+}
+
+function usableCapacity(value: number | null | undefined) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? value
+    : undefined;
+}
+
+export function contextPercent(usage: ContextUtilization) {
+  const tokens = usableTokens(usage.tokens);
+  const capacity = usableCapacity(usage.contextWindow);
+  if (tokens === undefined || capacity === undefined) return undefined;
+  return Math.round(Math.min(100, Math.max(0, (tokens / capacity) * 100)));
+}
+
+export function formatCompactTokens(count: number) {
+  if (count < 1000) return Math.round(count).toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1000000).toFixed(1)}M`;
+}
+
+/**
+ * Render `%/capacity`. If occupancy is unknown, retain the useful capacity
+ * as `?%/capacity`; with no valid capacity, omit the statistic entirely.
+ */
+export function formatContextUtilization(usage: ContextUtilization) {
+  const capacity = usableCapacity(usage.contextWindow);
+  if (capacity === undefined) return "";
+  const percent = contextPercent(usage);
+  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
+}
+
+interface ActivityCounts {
+  running: number;
+  done: number;
+  failed: number;
+}
+
+const SQUARE = "■";
+
+export function formatActivityStatus(theme: Theme, counts: ActivityCounts) {
+  const parts: string[] = [];
+  if (counts.running > 0) {
+    parts.push(theme.fg("warning", `${SQUARE} ${counts.running} running`));
+  }
+  if (counts.done > 0) {
+    parts.push(theme.fg("success", `${SQUARE} ${counts.done} done`));
+  }
+  if (counts.failed > 0) {
+    parts.push(theme.fg("error", `${SQUARE} ${counts.failed} failed`));
+  }
+  parts.push(theme.fg("accent", "/subagents") + theme.fg("dim", " to view"));
+
+  return `${theme.fg("muted", "subagents:")} ${parts.join(theme.fg("dim", " · "))}`;
+}