@asterxsk/kiln 0.1.0 → 0.3.0

package/agent/extensions/shared/child-session.ts

@@ -1,148 +1,148 @@
-import * as path from "node:path";
-import {
-  DefaultResourceLoader,
-  getAgentDir,
-  ProjectTrustStore,
-  SettingsManager,
-  type AgentSession,
-  type SessionShutdownEvent,
-} from "@earendil-works/pi-coding-agent";
-
-const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
-
-/** Tools that headless children must not receive. Everything else stays enabled. */
-export const CHILD_EXCLUDED_TOOL_NAMES = [
-  "subagent_spawn",
-  "subagent_wait",
-  "subagent_cancel",
-  "subagent_check",
-  "subagent_list",
-  "workflow",
-  "ask_user",
-] as const;
-
-/** Fresh SDK options avoid turning the denylist into an accidental allowlist. */
-export function childToolPolicy() {
-  return { excludeTools: [...CHILD_EXCLUDED_TOOL_NAMES] };
-}
-
-export interface ChildResourceOptions {
-  cwd: string;
-  projectTrusted: boolean;
-  appendSystemPrompt?: string[];
-  agentDir?: string;
-}
-
-/** Load normal global/package resources and trust-gated project resources. */
-export async function createChildResources(options: ChildResourceOptions) {
-  const agentDir = options.agentDir ?? getAgentDir();
-  const settingsManager = SettingsManager.create(options.cwd, agentDir, {
-    projectTrusted: options.projectTrusted,
-  });
-  const loader = new DefaultResourceLoader({
-    cwd: options.cwd,
-    agentDir,
-    settingsManager,
-    ...(options.appendSystemPrompt
-      ? { appendSystemPrompt: options.appendSystemPrompt }
-      : {}),
-  });
-  await loader.reload();
-  return { loader, settingsManager };
-}
-
-/**
- * Same-directory children inherit the live parent decision. An alternate cwd
- * is trusted only when Pi's persisted trust store explicitly trusts it (or a
- * containing directory); unreadable/invalid trust data fails closed.
- */
-export function resolveStandaloneChildProjectTrust(options: {
-  parentCwd: string;
-  childCwd: string;
-  parentTrusted: boolean;
-  agentDir?: string;
-}) {
-  if (path.resolve(options.childCwd) === path.resolve(options.parentCwd)) {
-    return options.parentTrusted;
-  }
-  try {
-    const trustStore = new ProjectTrustStore(options.agentDir ?? getAgentDir());
-    return trustStore.get(options.childCwd) === true;
-  } catch {
-    return false;
-  }
-}
-
-/** Start child extension session hooks/resources in headless print mode. */
-export async function bindChildSessionExtensions(
-  session: Pick<AgentSession, "bindExtensions">,
-) {
-  await session.bindExtensions({ mode: "print" });
-}
-
-interface ChildExtensionRunner {
-  hasHandlers(eventType: string): boolean;
-  emit(event: SessionShutdownEvent): Promise<unknown>;
-}
-
-export interface DisposableChildSession {
-  readonly extensionRunner: ChildExtensionRunner;
-  dispose(): void;
-}
-
-const childShutdowns = new WeakMap<object, Promise<void>>();
-
-function waitBounded(operation: Promise<unknown>, timeoutMs: number) {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<void>((resolve) => {
-    timer = setTimeout(resolve, timeoutMs);
-  });
-  return Promise.race([
-    operation.then(
-      () => undefined,
-      () => undefined,
-    ),
-    timeout,
-  ])
-    .catch(() => {})
-    .finally(() => {
-      if (timer) clearTimeout(timer);
-    });
-}
-
-/**
- * Emit child session_shutdown once, then dispose once. Hook failures and a
- * bounded hook deadline never prevent disposal.
- */
-export function shutdownAndDisposeChildSession(
-  session: DisposableChildSession,
-  options: { timeoutMs?: number } = {},
-) {
-  const existing = childShutdowns.get(session);
-  if (existing) return existing;
-
-  const shutdown = (async () => {
-    try {
-      if (session.extensionRunner.hasHandlers("session_shutdown")) {
-        await waitBounded(
-          session.extensionRunner.emit({
-            type: "session_shutdown",
-            reason: "quit",
-          }),
-          options.timeoutMs ?? CHILD_SHUTDOWN_TIMEOUT_MS,
-        );
-      }
-    } catch {
-      // Extension runner inspection/emission is best-effort during teardown.
-    } finally {
-      try {
-        session.dispose();
-      } catch {
-        // Disposal is terminal and must remain idempotent for callers.
-      }
-    }
-  })();
-
-  childShutdowns.set(session, shutdown);
-  return shutdown;
-}
+import * as path from "node:path";
+import {
+  DefaultResourceLoader,
+  getAgentDir,
+  ProjectTrustStore,
+  SettingsManager,
+  type AgentSession,
+  type SessionShutdownEvent,
+} from "@earendil-works/pi-coding-agent";
+
+const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
+
+/** Tools that headless children must not receive. Everything else stays enabled. */
+export const CHILD_EXCLUDED_TOOL_NAMES = [
+  "subagent_spawn",
+  "subagent_wait",
+  "subagent_cancel",
+  "subagent_check",
+  "subagent_list",
+  "workflow",
+  "ask_user",
+] as const;
+
+/** Fresh SDK options avoid turning the denylist into an accidental allowlist. */
+export function childToolPolicy() {
+  return { excludeTools: [...CHILD_EXCLUDED_TOOL_NAMES] };
+}
+
+export interface ChildResourceOptions {
+  cwd: string;
+  projectTrusted: boolean;
+  appendSystemPrompt?: string[];
+  agentDir?: string;
+}
+
+/** Load normal global/package resources and trust-gated project resources. */
+export async function createChildResources(options: ChildResourceOptions) {
+  const agentDir = options.agentDir ?? getAgentDir();
+  const settingsManager = SettingsManager.create(options.cwd, agentDir, {
+    projectTrusted: options.projectTrusted,
+  });
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir,
+    settingsManager,
+    ...(options.appendSystemPrompt
+      ? { appendSystemPrompt: options.appendSystemPrompt }
+      : {}),
+  });
+  await loader.reload();
+  return { loader, settingsManager };
+}
+
+/**
+ * Same-directory children inherit the live parent decision. An alternate cwd
+ * is trusted only when Pi's persisted trust store explicitly trusts it (or a
+ * containing directory); unreadable/invalid trust data fails closed.
+ */
+export function resolveStandaloneChildProjectTrust(options: {
+  parentCwd: string;
+  childCwd: string;
+  parentTrusted: boolean;
+  agentDir?: string;
+}) {
+  if (path.resolve(options.childCwd) === path.resolve(options.parentCwd)) {
+    return options.parentTrusted;
+  }
+  try {
+    const trustStore = new ProjectTrustStore(options.agentDir ?? getAgentDir());
+    return trustStore.get(options.childCwd) === true;
+  } catch {
+    return false;
+  }
+}
+
+/** Start child extension session hooks/resources in headless print mode. */
+export async function bindChildSessionExtensions(
+  session: Pick<AgentSession, "bindExtensions">,
+) {
+  await session.bindExtensions({ mode: "print" });
+}
+
+interface ChildExtensionRunner {
+  hasHandlers(eventType: string): boolean;
+  emit(event: SessionShutdownEvent): Promise<unknown>;
+}
+
+export interface DisposableChildSession {
+  readonly extensionRunner: ChildExtensionRunner;
+  dispose(): void;
+}
+
+const childShutdowns = new WeakMap<object, Promise<void>>();
+
+function waitBounded(operation: Promise<unknown>, timeoutMs: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, timeoutMs);
+  });
+  return Promise.race([
+    operation.then(
+      () => undefined,
+      () => undefined,
+    ),
+    timeout,
+  ])
+    .catch(() => {})
+    .finally(() => {
+      if (timer) clearTimeout(timer);
+    });
+}
+
+/**
+ * Emit child session_shutdown once, then dispose once. Hook failures and a
+ * bounded hook deadline never prevent disposal.
+ */
+export function shutdownAndDisposeChildSession(
+  session: DisposableChildSession,
+  options: { timeoutMs?: number } = {},
+) {
+  const existing = childShutdowns.get(session);
+  if (existing) return existing;
+
+  const shutdown = (async () => {
+    try {
+      if (session.extensionRunner.hasHandlers("session_shutdown")) {
+        await waitBounded(
+          session.extensionRunner.emit({
+            type: "session_shutdown",
+            reason: "quit",
+          }),
+          options.timeoutMs ?? CHILD_SHUTDOWN_TIMEOUT_MS,
+        );
+      }
+    } catch {
+      // Extension runner inspection/emission is best-effort during teardown.
+    } finally {
+      try {
+        session.dispose();
+      } catch {
+        // Disposal is terminal and must remain idempotent for callers.
+      }
+    }
+  })();
+
+  childShutdowns.set(session, shutdown);
+  return shutdown;
+}

package/agent/extensions/shared/context-utilization.test.ts

@@ -1,48 +1,48 @@
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import {
-  contextPercent,
-  formatContextUtilization,
-} from "./context-utilization.ts";
-
-test("formats current context occupancy against model capacity", () => {
-  assert.equal(
-    formatContextUtilization({ tokens: 26_040, contextWindow: 372_000 }),
-    "7%/372k",
-  );
-});
-
-test("formats the latest post-compaction usage rather than prior cumulative usage", () => {
-  const latestUsage = { tokens: 18_000, contextWindow: 200_000 };
-  assert.equal(formatContextUtilization(latestUsage), "9%/200k");
-});
-
-test("clamps over-capacity and nonsensical token values", () => {
-  assert.equal(
-    contextPercent({ tokens: 500_000, contextWindow: 200_000 }),
-    100,
-  );
-  assert.equal(
-    formatContextUtilization({
-      tokens: Number.POSITIVE_INFINITY,
-      contextWindow: 200_000,
-    }),
-    "?%/200k",
-  );
-  assert.equal(
-    formatContextUtilization({ tokens: -1, contextWindow: 200_000 }),
-    "?%/200k",
-  );
-});
-
-test("handles missing usage or capacity without NaN or Infinity", () => {
-  assert.equal(
-    formatContextUtilization({ tokens: null, contextWindow: 372_000 }),
-    "?%/372k",
-  );
-  assert.equal(formatContextUtilization({ tokens: 12_000 }), "");
-  assert.equal(
-    formatContextUtilization({ tokens: 12_000, contextWindow: 0 }),
-    "",
-  );
-});
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  contextPercent,
+  formatContextUtilization,
+} from "./context-utilization.ts";
+
+test("formats current context occupancy against model capacity", () => {
+  assert.equal(
+    formatContextUtilization({ tokens: 26_040, contextWindow: 372_000 }),
+    "7%/372k",
+  );
+});
+
+test("formats the latest post-compaction usage rather than prior cumulative usage", () => {
+  const latestUsage = { tokens: 18_000, contextWindow: 200_000 };
+  assert.equal(formatContextUtilization(latestUsage), "9%/200k");
+});
+
+test("clamps over-capacity and nonsensical token values", () => {
+  assert.equal(
+    contextPercent({ tokens: 500_000, contextWindow: 200_000 }),
+    100,
+  );
+  assert.equal(
+    formatContextUtilization({
+      tokens: Number.POSITIVE_INFINITY,
+      contextWindow: 200_000,
+    }),
+    "?%/200k",
+  );
+  assert.equal(
+    formatContextUtilization({ tokens: -1, contextWindow: 200_000 }),
+    "?%/200k",
+  );
+});
+
+test("handles missing usage or capacity without NaN or Infinity", () => {
+  assert.equal(
+    formatContextUtilization({ tokens: null, contextWindow: 372_000 }),
+    "?%/372k",
+  );
+  assert.equal(formatContextUtilization({ tokens: 12_000 }), "");
+  assert.equal(
+    formatContextUtilization({ tokens: 12_000, contextWindow: 0 }),
+    "",
+  );
+});

package/agent/extensions/shared/context-utilization.ts

@@ -1,47 +1,47 @@
-/** Compact, defensive context-window utilization formatting for child agents. */
-
-export interface ContextUtilization {
-  /** Current conversation context occupancy; null while it is unknown after compaction. */
-  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 temporarily unknown (notably directly
- * after compaction), retain the useful model capacity as `?%/capacity`. If no
- * valid capacity is available, omit the statistic because no percentage can
- * be computed.
- */
-export function formatContextUtilization(usage: ContextUtilization) {
-  const capacity = usableCapacity(usage.contextWindow);
-  if (capacity === undefined) return "";
-  const percent = contextPercent(usage);
-  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
-}
+/** Compact, defensive context-window utilization formatting for child agents. */
+
+export interface ContextUtilization {
+  /** Current conversation context occupancy; null while it is unknown after compaction. */
+  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 temporarily unknown (notably directly
+ * after compaction), retain the useful model capacity as `?%/capacity`. If no
+ * valid capacity is available, omit the statistic because no percentage can
+ * be computed.
+ */
+export function formatContextUtilization(usage: ContextUtilization) {
+  const capacity = usableCapacity(usage.contextWindow);
+  if (capacity === undefined) return "";
+  const percent = contextPercent(usage);
+  return `${percent === undefined ? "?" : percent}%/${formatCompactTokens(capacity)}`;
+}