@asterxsk/kiln 0.1.0

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

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

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

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

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

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

package/agent/extensions/shared/dashboard-state.ts

@@ -0,0 +1,99 @@
+export const MODEL_INFO_CHANNEL = "dashboard:model-info";
+export const GIT_INFO_CHANNEL = "dashboard:git-info";
+export const REFRESH_CHANNEL = "dashboard:refresh";
+
+export interface ModelInfoState {
+  provider: string;
+  modelId: string;
+  modelName: string;
+  thinking: string;
+  contextTokens: number | null;
+  contextWindow: number;
+  contextPercent: number | null;
+  cost: number;
+  tokensPerSecond: number | null;
+  generating: boolean;
+}
+
+export interface PullRequestInfo {
+  number: number;
+  url: string;
+  isDraft: boolean;
+}
+
+export interface GitInfoState {
+  isRepository: boolean;
+  branch: string | null;
+  changedFiles: number;
+  pullRequest: PullRequestInfo | null;
+}
+
+export function emptyModelInfoState(): ModelInfoState {
+  return {
+    provider: "",
+    modelId: "no-model",
+    modelName: "No model",
+    thinking: "off",
+    contextTokens: null,
+    contextWindow: 0,
+    contextPercent: null,
+    cost: 0,
+    tokensPerSecond: null,
+    generating: false,
+  };
+}
+
+export function emptyGitInfoState(): GitInfoState {
+  return {
+    isRepository: false,
+    branch: null,
+    changedFiles: 0,
+    pullRequest: null,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isNullableNumber(value: unknown) {
+  return value === null || typeof value === "number";
+}
+
+export function isModelInfoState(value: unknown): value is ModelInfoState {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.provider === "string" &&
+    typeof value.modelId === "string" &&
+    typeof value.modelName === "string" &&
+    typeof value.thinking === "string" &&
+    isNullableNumber(value.contextTokens) &&
+    typeof value.contextWindow === "number" &&
+    isNullableNumber(value.contextPercent) &&
+    typeof value.cost === "number" &&
+    isNullableNumber(value.tokensPerSecond) &&
+    typeof value.generating === "boolean"
+  );
+}
+
+function isPullRequestInfo(value: unknown): value is PullRequestInfo {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.number === "number" &&
+    typeof value.url === "string" &&
+    typeof value.isDraft === "boolean"
+  );
+}
+
+export function isGitInfoState(value: unknown): value is GitInfoState {
+  if (!isRecord(value)) return false;
+
+  return (
+    typeof value.isRepository === "boolean" &&
+    (value.branch === null || typeof value.branch === "string") &&
+    typeof value.changedFiles === "number" &&
+    (value.pullRequest === null || isPullRequestInfo(value.pullRequest))
+  );
+}

package/agent/extensions/shared/install.ps1

@@ -0,0 +1,23 @@
+#!/usr/bin/env pwsh
+# Per-extension installer — Windows / PowerShell
+# Installs npm dependencies for this extension. No-op if no package.json.
+$ErrorActionPreference = "Stop"
+$extDir = $PSScriptRoot
+if (-not $extDir) { $extDir = Split-Path -Parent $MyInvocation.MyCommand.Path }
+if (-not (Test-Path "$extDir/package.json")) {
+  Write-Host "  - no package.json — skipping" -ForegroundColor DarkGray
+  exit 0
+}
+if (-not (Get-Command npm -ErrorAction SilentlyContinue)) {
+  Write-Host "  x npm not found — install Node.js 22+" -ForegroundColor Red
+  exit 1
+}
+if (Test-Path "$extDir/package-lock.json") {
+  Write-Host "  - npm ci" -ForegroundColor DarkGray
+  npm --prefix $extDir ci --no-audit --no-fund
+} else {
+  Write-Host "  - npm install" -ForegroundColor DarkGray
+  npm --prefix $extDir install --no-audit --no-fund
+}
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+Write-Host "  + done" -ForegroundColor Green

package/agent/extensions/shared/install.sh

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Per-extension installer — macOS / Linux
+# Installs npm dependencies for this extension. No-op if no package.json.
+set -eu
+EXT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ ! -f "$EXT_DIR/package.json" ]; then
+  echo "  · no package.json — skipping"
+  exit 0
+fi
+if ! command -v npm >/dev/null 2>&1; then
+  echo "  ✖ npm not found — install Node.js 22+" >&2
+  exit 1
+fi
+if [ -f "$EXT_DIR/package-lock.json" ]; then
+  echo "  · npm ci"
+  npm --prefix "$EXT_DIR" ci --no-audit --no-fund
+else
+  echo "  · npm install"
+  npm --prefix "$EXT_DIR" install --no-audit --no-fund
+fi
+echo "  ✓ done"

package/agent/extensions/shared/tool-call-timeout.test.ts

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import {
+  createToolCallTimeoutGuard,
+  runWithToolCallTimeout,
+  CHILD_TOOL_CALL_TIMEOUT_MS,
+  ToolCallTimeoutError,
+} from "./tool-call-timeout.ts";
+
+test("the production timeout error names the tool and three-minute limit", () => {
+  assert.equal(
+    new ToolCallTimeoutError("fixture_tool", CHILD_TOOL_CALL_TIMEOUT_MS)
+      .message,
+    'Tool call "fixture_tool" timed out after 3 minutes.',
+  );
+});
+
+test("a hung tool call fails clearly and receives an abort signal", async () => {
+  let executionSignal: AbortSignal | undefined;
+
+  await assert.rejects(
+    runWithToolCallTimeout("hung_fixture", 10, undefined, (signal) => {
+      executionSignal = signal;
+      return new Promise(() => {});
+    }),
+    (error: unknown) => {
+      assert.equal(error instanceof ToolCallTimeoutError, true);
+      assert.equal(
+        error instanceof Error ? error.message : "",
+        'Tool call "hung_fixture" timed out after 10 ms.',
+      );
+      return true;
+    },
+  );
+
+  assert.equal(executionSignal?.aborted, true);
+  assert.equal(executionSignal?.reason instanceof ToolCallTimeoutError, true);
+});
+
+test("parent cancellation still stops the timeout wrapper immediately", async () => {
+  const controller = new AbortController();
+  const reason = new Error("cancelled fixture");
+  const pending = runWithToolCallTimeout(
+    "hung_fixture",
+    60_000,
+    controller.signal,
+    () => new Promise(() => {}),
+  );
+
+  controller.abort(reason);
+
+  await assert.rejects(pending, (error: unknown) => error === reason);
+});
+
+test("the guard wraps each definition once and can discover later tools", () => {
+  const definitions = new Map<string, ToolDefinition>();
+  const createDefinition = (name: string): ToolDefinition => ({
+    name,
+    label: name,
+    description: name,
+    parameters: Type.Object({}),
+    async execute() {
+      return { content: [{ type: "text", text: "done" }], details: {} };
+    },
+  });
+  const first = createDefinition("first");
+  definitions.set(first.name, first);
+  const registry = {
+    getAllTools: () => [...definitions.keys()].map((name) => ({ name })),
+    getToolDefinition: (name: string) => definitions.get(name),
+  };
+  const guard = createToolCallTimeoutGuard(10);
+
+  const firstExecute = first.execute;
+  guard.apply(registry);
+  const firstWrappedExecute = first.execute;
+  assert.notEqual(firstWrappedExecute, firstExecute);
+
+  const second = createDefinition("second");
+  const secondExecute = second.execute;
+  definitions.set(second.name, second);
+  guard.apply(registry);
+
+  assert.equal(first.execute, firstWrappedExecute);
+  assert.notEqual(second.execute, secondExecute);
+});
+
+test("successful and terminating tool results pass through unchanged", async () => {
+  const result = {
+    content: [{ type: "text" as const, text: "recorded" }],
+    details: { value: "fixture" },
+    terminate: true,
+  };
+
+  assert.equal(
+    await runWithToolCallTimeout(
+      "structured_output",
+      10,
+      undefined,
+      async () => result,
+    ),
+    result,
+  );
+});
+
+test("the timeout is fresh for each tool call, not shared across calls", async () => {
+  const execute = () =>
+    runWithToolCallTimeout("slow_fixture", 100, undefined, async () => {
+      await new Promise((resolve) => setTimeout(resolve, 60));
+      return "done";
+    });
+
+  assert.equal(await execute(), "done");
+  assert.equal(await execute(), "done");
+});

package/agent/extensions/shared/tool-call-timeout.ts

@@ -0,0 +1,104 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+export const CHILD_TOOL_CALL_TIMEOUT_MS = 3 * 60 * 1_000;
+
+interface ToolRegistry {
+  getAllTools(): Array<{ name: string }>;
+  getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+function formatTimeout(timeoutMs: number) {
+  if (timeoutMs % 60_000 === 0) {
+    const minutes = timeoutMs / 60_000;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  if (timeoutMs % 1_000 === 0) {
+    const seconds = timeoutMs / 1_000;
+    return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  }
+  return `${timeoutMs} ms`;
+}
+
+export class ToolCallTimeoutError extends Error {
+  constructor(toolName: string, timeoutMs: number) {
+    super(
+      `Tool call "${toolName}" timed out after ${formatTimeout(timeoutMs)}.`,
+    );
+    this.name = "ToolCallTimeoutError";
+  }
+}
+
+export async function runWithToolCallTimeout<T>(
+  toolName: string,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+  execute: (signal: AbortSignal) => Promise<T>,
+) {
+  const timeoutController = new AbortController();
+  const executionSignal = signal
+    ? AbortSignal.any([signal, timeoutController.signal])
+    : timeoutController.signal;
+  const timeoutError = new ToolCallTimeoutError(toolName, timeoutMs);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(timeoutError);
+      timeoutController.abort(timeoutError);
+    }, timeoutMs);
+  });
+
+  let removeAbortListener: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    const onAbort = () => {
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error(`Tool call "${toolName}" was aborted.`),
+      );
+    };
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+  });
+
+  try {
+    return await Promise.race([execute(executionSignal), timeout, aborted]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    removeAbortListener?.();
+  }
+}
+
+/**
+ * Wrap every currently registered child tool with an independent execution
+ * timeout. Calling apply() again is safe and picks up tools registered later.
+ */
+export function createToolCallTimeoutGuard(
+  timeoutMs = CHILD_TOOL_CALL_TIMEOUT_MS,
+) {
+  const wrapped = new WeakSet<ToolDefinition>();
+
+  const wrap = (definition: ToolDefinition) => {
+    if (wrapped.has(definition)) return;
+    wrapped.add(definition);
+
+    const execute = definition.execute;
+    definition.execute = async (toolCallId, params, signal, onUpdate, ctx) =>
+      runWithToolCallTimeout(definition.name, timeoutMs, signal, (signal) =>
+        execute.call(definition, toolCallId, params, signal, onUpdate, ctx),
+      );
+  };
+
+  return {
+    apply(session: ToolRegistry) {
+      for (const { name } of session.getAllTools()) {
+        const definition = session.getToolDefinition(name);
+        if (definition) wrap(definition);
+      }
+    },
+  };
+}

package/agent/extensions/skillsconf/README.md

@@ -0,0 +1,74 @@
+# skillsconf
+
+Per-skill visibility manager for pi, with **packages** (named groups) for mass enable/disable.
+
+Disabled skills are stripped from the system prompt every turn (via `before_agent_start`),
+so they cost zero context. Nothing is moved on disk — packages are just named lists
+stored in settings.
+
+```
+/skillsconf
+```
+
+## Keybindings
+
+- `↑` / `↓` or `j` / `k` — navigate; `Home`/`End` (`g`/`G`) jump
+- `Space` — toggle the selected skill **or** the selected package (whole group on/off)
+- `/` — fuzzy filter by name/description; `↑`/`↓` exit typing (filter kept) and
+  move; `←`/`→` edit the query; `Esc` clears, `Enter` keeps filter
+- `e` — toggle grouped view (packages + ungrouped skills) vs flat list of all skills
+- `n` — new package (type a name, `Enter` creates, `Esc` cancels)
+- `a` — on a package: enter assign mode (cursor jumps to skills, `Space` toggles
+  membership, `Enter` done, `Esc` cancel without changing the package)
+- `d` — delete what's under the cursor (package group, or skill files from disk)
+  with a `y`/`n` confirm (`Esc` cancels)
+- `s` — save to settings, stay open (`● unsaved — press s to save` clears; takes
+  effect next turn)
+- `Esc` / `q` — quit (`s` first if you want to keep changes); quitting with pending
+  changes shows `changes discarded (not saved)`
+Package rows show `(enabled/total)`: `◉` all on, `◍` partial, `○` all off / empty.
+Each package row leads with an accent `▸` marker and bold name so it stands out
+from skills.
+
+Skills that belong to a package are hidden from the main list and managed via
+their package row (grouped view). `e` switches to a flat list showing every
+skill; `/` search and assign mode always see every skill, with a `⟨package⟩`
+tag showing membership.
+
+## Persistence
+
+Writes `disabledSkills` and `skillPackages` in `~/.pi/agent/settings.json`:
+
+- Nothing disabled + no packages → both keys removed to keep settings clean
+- `skillPackages` maps package name → sorted member skill names (empty packages kept)
+- Stale names (skills no longer on disk) are filtered on the next save
+
+No reload happens on save — the prompt filter re-reads settings from disk every
+turn, so changes apply from the next agent turn on. Physically deleted skills
+vanish from the loaded list after `/reload`.
+
+## Keyboard shortcut
+
+`Ctrl+Alt+S` opens skillsconf when supported by the host.
+
+## How filtering works
+
+pi renders loaded skills as `<skill><name>…` blocks inside `<available_skills>`.
+The extension removes the blocks whose `<name>` is in `disabledSkills` (verbatim block
+surgery — kept blocks are byte-identical). When all skills are disabled, the whole
+section including its intro is removed.
+
+## Development
+
+```bash
+npx tsc --noEmit --project ./tsconfig.json
+```
+
+Tests are plain `node:assert` files (same style as `modelconf`):
+
+```bash
+npx tsc --project ./tsconfig.json --outDir /tmp/skillsconf-test
+node --test /tmp/skillsconf-test/src/filter.test.js \
+  /tmp/skillsconf-test/src/persistence.test.js \
+  /tmp/skillsconf-test/src/ui/SkillConfView.test.js
+```