@windowkit/agent-chat 0.0.0-stage → 0.1.0

package/dist/view/look.js

@@ -0,0 +1,37 @@
+// The palette the chat draws with, read from the theme in force, so the chat
+// takes the app's look and the desktop's light or dark scheme.
+import { useMemo } from 'react';
+import { useTheme } from 'react-x11';
+import { tint } from 'react-x11/style';
+export function useLook() {
+    const theme = useTheme();
+    return useMemo(() => {
+        const text = String(theme.text ?? '#2d3436');
+        return {
+            text,
+            muted: String(theme.textMuted ?? '#7f8c8d'),
+            border: String(theme.border ?? '#b2bec3'),
+            surface: String(theme.surface ?? '#f1f2f6'),
+            background: String(theme.background ?? 'white'),
+            accent: String(theme.accent ?? '#2980b9'),
+            danger: String(theme.danger ?? '#c0392b'),
+            success: String(theme.success ?? '#27ae60'),
+            warning: String(theme.warning ?? '#e67e22'),
+            mono: String(theme.monoFamily ?? 'monospace'),
+            bubble: tint(text, 0.07),
+        };
+    }, [theme]);
+}
+/** At most `max` lines: the first and last halves, and how many were cut. */
+export function clipLines(text, max = 200) {
+    const lines = text.split('\n');
+    if (lines.length <= max)
+        return text;
+    const half = Math.floor(max / 2);
+    return [
+        ...lines.slice(0, half),
+        `… ${lines.length - max} more lines …`,
+        ...lines.slice(-half),
+    ].join('\n');
+}
+//# sourceMappingURL=look.js.map

package/dist/view/look.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"look.js","sourceRoot":"","sources":["../../src/view/look.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+DAA+D;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAiBvC,MAAM,UAAU,OAAO;IACrB,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC;QAC7C,OAAO;YACL,IAAI;YACJ,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,IAAI,SAAS,CAAC;YAC3C,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC;YACzC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,SAAS,CAAC;YAC3C,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,OAAO,CAAC;YAC/C,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC;YACzC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC;YACzC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,SAAS,CAAC;YAC3C,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,IAAI,SAAS,CAAC;YAC3C,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,WAAW,CAAC;YAC7C,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC;SACzB,CAAC;IACJ,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;AACd,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,GAAG,GAAG,GAAG;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;IACjC,OAAO;QACL,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;QACvB,KAAK,KAAK,CAAC,MAAM,GAAG,GAAG,eAAe;QACtC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;KACtB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/view/types.d.ts

@@ -0,0 +1,50 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { IconName } from 'react-x11';
+import type { FenceInfo } from '@react-x11/components/markdown';
+import type { AgentSession } from '../core/session.js';
+import type { ToolDef, ToolParameters, InferInput, ToolRenderInfo } from '../core/tools.js';
+import type { AgentMessage } from '../core/types.js';
+export type { FenceInfo };
+/**
+ * How a fenced block with this language is drawn: a function, or the
+ * function and a line that tells the agent the format exists.
+ */
+export type FenceEntry = ((fence: FenceInfo) => ReactNode) | {
+    render: (fence: FenceInfo) => ReactNode;
+    describe?: string;
+};
+/**
+ * A component a reply may name as a tag on its own line: `<Ticket id="12"/>`.
+ * A tag is a component iff its name is a key here; nothing is evaluated.
+ */
+export type ComponentEntry = ComponentType<Record<string, unknown>> | {
+    component: ComponentType<Record<string, unknown>>;
+    describe?: string;
+};
+/** What a code action is handed besides the fence. */
+export interface CodeActionContext {
+    session: AgentSession;
+    message: AgentMessage;
+    /** Put text on the clipboard. */
+    copy(text: string): Promise<void>;
+}
+/** A button on a fenced code block's header. */
+export interface CodeAction {
+    id: string;
+    label: string;
+    icon?: IconName;
+    /** Shown for a moment after `run` resolves: `'Copied'`. */
+    doneLabel?: string;
+    /** Default: every block. */
+    when?: (fence: FenceInfo) => boolean;
+    run(fence: FenceInfo, ctx: CodeActionContext): void | Promise<void>;
+}
+/** The built-in Copy. The default `codeActions` is `[copyCode]`. */
+export declare const copyCode: CodeAction;
+/** Draws a tool call: the part, its parsed input, and what `run` returned. */
+export type ToolRenderer = (info: ToolRenderInfo) => ReactNode;
+/** `defineTool`, with `render` typed for this view. */
+export declare function defineTool<P extends ToolParameters, O>(def: ToolDef<InferInput<P>, O, ReactNode> & {
+    parameters: P;
+}): ToolDef<InferInput<P>, O, ReactNode>;
+//# sourceMappingURL=types.d.ts.map

package/dist/view/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/view/types.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB,CAAC,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC,GACjC;IAAE,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC;IAAE,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC;IACrC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,oEAAoE;AACpE,eAAO,MAAM,QAAQ,EAAE,UAKrB,CAAC;AAEH,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,cAAc,KAAK,SAAS,CAAC;AAE/D,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,CAAC,SAAS,cAAc,EAAE,CAAC,EACpD,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,GAAG;IAAE,UAAU,EAAE,CAAC,CAAA;CAAE,GAC5D,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAEtC"}

package/dist/view/types.js

@@ -0,0 +1,14 @@
+// The view's own props: renderers and actions. Nothing here reaches the
+// session, but `describe` does reach the agent, as instructions.
+/** The built-in Copy. The default `codeActions` is `[copyCode]`. */
+export const copyCode = Object.freeze({
+    id: 'copy',
+    label: 'Copy',
+    doneLabel: 'Copied',
+    run: (fence, ctx) => ctx.copy(fence.text),
+});
+/** `defineTool`, with `render` typed for this view. */
+export function defineTool(def) {
+    return def;
+}
+//# sourceMappingURL=types.js.map

package/dist/view/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/view/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,iEAAiE;AAqDjE,oEAAoE;AACpE,MAAM,CAAC,MAAM,QAAQ,GAAe,MAAM,CAAC,MAAM,CAAC;IAChD,EAAE,EAAE,MAAM;IACV,KAAK,EAAE,MAAM;IACb,SAAS,EAAE,QAAQ;IACnB,GAAG,EAAE,CAAC,KAAgB,EAAE,GAAsB,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;CACxE,CAAC,CAAC;AAKH,uDAAuD;AACvD,MAAM,UAAU,UAAU,CACxB,GAA6D;IAE7D,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/view/use-agent.d.ts

@@ -0,0 +1,11 @@
+import { type AgentOptions, type AgentSession, type SessionSnapshot } from '../core/session.js';
+/**
+ * A session for this component's life: made at the first render from
+ * `options`, which are read once (give the component a new `key` to start
+ * over), and closed when the component unmounts. The component re-renders
+ * whenever the session changes.
+ */
+export declare function useAgent(options: AgentOptions): AgentSession;
+/** The session's current snapshot, re-rendering as it changes. */
+export declare function useSessionSnapshot(session: AgentSession): SessionSnapshot;
+//# sourceMappingURL=use-agent.d.ts.map

package/dist/view/use-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent.d.ts","sourceRoot":"","sources":["../../src/view/use-agent.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAiB5D;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CAEzE"}

package/dist/view/use-agent.js

@@ -0,0 +1,33 @@
+// The session as React state.
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createAgentSession, } from '../core/session.js';
+/**
+ * A session for this component's life: made at the first render from
+ * `options`, which are read once (give the component a new `key` to start
+ * over), and closed when the component unmounts. The component re-renders
+ * whenever the session changes.
+ */
+export function useAgent(options) {
+    const [session] = useState(() => createAgentSession(options));
+    useSessionSnapshot(session);
+    // Closed a turn after the unmount, not at it: StrictMode's development
+    // double mount unmounts and mounts again at once, and the session should
+    // survive that.
+    const mounted = useRef(0);
+    useEffect(() => {
+        mounted.current++;
+        return () => {
+            const at = --mounted.current;
+            setTimeout(() => {
+                if (mounted.current === at && at === 0)
+                    void session.close();
+            }, 0);
+        };
+    }, [session]);
+    return session;
+}
+/** The session's current snapshot, re-rendering as it changes. */
+export function useSessionSnapshot(session) {
+    return useSyncExternalStore(session.subscribe, () => session.snapshot);
+}
+//# sourceMappingURL=use-agent.js.map

package/dist/view/use-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-agent.js","sourceRoot":"","sources":["../../src/view/use-agent.ts"],"names":[],"mappings":"AAAA,8BAA8B;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,EACL,kBAAkB,GAInB,MAAM,oBAAoB,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAqB;IAC5C,MAAM,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,uEAAuE;IACvE,yEAAyE;IACzE,gBAAgB;IAChB,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,GAAG,EAAE;YACV,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC;YAC7B,UAAU,CAAC,GAAG,EAAE;gBACd,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC;oBAAE,KAAK,OAAO,CAAC,KAAK,EAAE,CAAC;YAC/D,CAAC,EAAE,CAAC,CAAC,CAAC;QACR,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACd,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,OAAqB;IACtD,OAAO,oBAAoB,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC"}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@windowkit/agent-chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An embeddable chat UI for local AI agent harnesses, for react-x11: the Claude Agent SDK first, your own tools as functions, your own renderers, and every action interceptable.",
+  "keywords": [
+    "react-x11",
+    "agent",
+    "claude",
+    "chat",
+    "ai",
+    "desktop"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/windowkit/agent-chat.git"
+  },
+  "homepage": "https://github.com/windowkit/agent-chat#readme",
+  "bugs": {
+    "url": "https://github.com/windowkit/agent-chat/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./drivers/claude": {
+      "types": "./dist/drivers/claude/index.d.ts",
+      "default": "./dist/drivers/claude/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "test": "tsx --test test/*.test.ts test/*.test.tsx",
+    "typecheck": "tsc -p tsconfig.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check:package": "tsx scripts/check-package.ts",
+    "examples:demo": "tsx examples/demo.tsx",
+    "examples:claude": "tsx examples/claude.tsx",
+    "examples:tools": "tsx examples/tools.tsx",
+    "examples:intercept": "tsx examples/intercept.tsx",
+    "examples:peers": "tsx examples/peers.tsx",
+    "screenshots": "tsx scripts/screenshot.tsx"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.3.300 <0.4.0",
+    "@react-x11/components": ">=0.38.0 <0.44.0",
+    "react": "^19.0.0",
+    "react-x11": "^2.56.3"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.319",
+    "@react-x11/components": "^0.43.0",
+    "@types/node": "^26.2.0",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^19.2.17",
+    "pngjs": "^7.0.0",
+    "prettier": "^3.6.0",
+    "react": "^19.2.8",
+    "react-x11": "^2.58.1",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2",
+    "zod": "^4.1.0"
+  }
+}

package/src/core/driver.ts

@@ -0,0 +1,191 @@
+// The seam between the session and a harness.
+//
+// A driver turns one harness's protocol into `DriverEvent`s, and asks the
+// session — through `DriverHost` — every question the protocol asks the
+// client: may this tool run, what did the user answer, run the app's tool.
+// It is public for the reason `ProcessHost` is in `@react-x11/components`:
+// driving a harness nobody wrapped yet should not need a fork.
+
+import type { AnyToolDef, ToolResult } from './tools.js';
+import type {
+  Attachment,
+  Capabilities,
+  CoreToolKey,
+  MessageSource,
+  PeerSource,
+  PermissionPolicy,
+  PlanEntry,
+  Question,
+  SessionInfo,
+  ToolCall,
+  ToolKind,
+  ToolOutput,
+  ToolState,
+  Usage,
+} from './types.js';
+
+/**
+ * What a driver reports. Deltas, never snapshots: the reducer accumulates
+ * them, so a tool part cannot vanish because a driver forgot to repeat it.
+ * `parent` names the tool call a subagent's event belongs under.
+ */
+export type DriverEvent =
+  /** Assistant text: `delta` appends, `text` replaces (a finished block). */
+  | {
+      type: 'text';
+      id: string;
+      delta?: string;
+      text?: string;
+      done?: boolean;
+      reasoning?: boolean;
+      parent?: string;
+    }
+  | {
+      type: 'tool-start';
+      id: string;
+      name: string;
+      label?: string;
+      kind?: ToolKind;
+      title?: string;
+      input?: unknown;
+      app?: boolean;
+      parent?: string;
+    }
+  /** A piece of the arguments' JSON. */
+  | { type: 'tool-input'; id: string; delta: string }
+  | {
+      type: 'tool-update';
+      id: string;
+      input?: unknown;
+      title?: string;
+      kind?: ToolKind;
+      state?: ToolState;
+      /** Replaces the outputs. */
+      output?: readonly ToolOutput[];
+      /** Appended to them. */
+      append?: ToolOutput;
+      progress?: string;
+    }
+  | {
+      type: 'tool-end';
+      id: string;
+      state: 'done' | 'error' | 'denied' | 'cancelled';
+      output?: readonly ToolOutput[];
+      error?: string;
+    }
+  | { type: 'plan'; entries: readonly PlanEntry[]; parent?: string }
+  /**
+   * A message the harness took from someone other than the user — another
+   * session, a channel — and is acting on. A turn starts with it if none is
+   * running, as one does for `send`.
+   */
+  | { type: 'message'; id: string; text: string; from: MessageSource }
+  | { type: 'notice'; level: 'info' | 'warning' | 'error'; text: string }
+  | { type: 'info'; info: Partial<SessionInfo> }
+  | { type: 'usage'; usage: Usage }
+  | {
+      type: 'turn-end';
+      reason: 'done' | 'stopped' | 'error' | 'limit';
+      error?: string;
+    };
+
+/** The policy's answer, fast, with no user involved. */
+export type GateDecision =
+  | { behavior: 'allow'; input?: unknown }
+  | { behavior: 'deny'; message: string }
+  /** The user must decide: the driver routes the call to `approve`. */
+  | { behavior: 'ask' }
+  /** No opinion: the harness's own permission mode decides. */
+  | { behavior: 'defer' };
+
+/** The user's answer, through the approval row. */
+export type ApprovalResult =
+  | { behavior: 'allow'; input?: unknown }
+  | { behavior: 'deny'; message: string; interrupt?: boolean };
+
+/** What a driver may ask of the session. */
+export interface DriverHost {
+  readonly config: DriverConfig;
+  emit(event: DriverEvent): void;
+  /** Before a tool runs: the app's `onToolCall`, then the policy. Never
+   *  waits on the user, so a harness hook with a timeout can call it. */
+  gate(call: ToolCall): Promise<GateDecision>;
+  /** The approval row: waits on the user, and while the session is paused.
+   *  Has no timeout. */
+  approve(call: ToolCall, signal?: AbortSignal): Promise<ApprovalResult>;
+  /** A question for the user (`AskUserQuestion`). `null` if dismissed. */
+  ask(
+    id: string,
+    questions: readonly Question[],
+    signal?: AbortSignal,
+  ): Promise<Record<string, string> | null>;
+  /** Run one of the app's tools. Never throws: a failure is a result. */
+  runTool(
+    name: string,
+    input: unknown,
+    ctx: { callId?: string; signal?: AbortSignal },
+  ): Promise<ToolResult>;
+}
+
+/** The session's options, resolved for a driver. */
+export interface DriverConfig {
+  cwd: string;
+  folders: readonly string[];
+  /** Appended to the harness's own system prompt. Empty for none. */
+  instructions: string;
+  /** Replaces the harness's system prompt. */
+  systemPrompt?: string;
+  /** Categories and harness names switched off. */
+  removed: readonly string[];
+  /** Categories and harness names that always ask. */
+  asking: readonly string[];
+  /** Categories replaced by one of `tools`, by the tool's name. */
+  replaced: Readonly<Partial<Record<CoreToolKey, string>>>;
+  /** The app's tools, replacements included, by name. */
+  tools: ReadonlyMap<string, AnyToolDef>;
+  permissions: PermissionPolicy;
+  model?: string;
+  mode?: string;
+  /** A harness session id to resume. */
+  resume?: string;
+  settings: 'cli' | 'isolated';
+  driverOptions: Readonly<Record<string, unknown>>;
+}
+
+/** A message on its way to the harness. */
+export interface OutgoingMessage {
+  /** The transcript's id for it. */
+  id: string;
+  text: string;
+  attachments: readonly Attachment[];
+  /** Sent while a turn runs; the driver delivers it as steering. */
+  steer: boolean;
+  /** Sent on another session's behalf. Absent: the user's own. */
+  from?: PeerSource;
+}
+
+export interface DriverSession {
+  readonly capabilities: Capabilities;
+  send(message: OutgoingMessage): void;
+  /** Stop the turn. The driver ends it with `turn-end` `'stopped'`. */
+  interrupt(): Promise<void>;
+  setModel?(id: string): Promise<void>;
+  setMode?(id: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface AgentDriver {
+  /** `'claude'`, `'fake'`: shown, and `SessionInfo.agent`. */
+  readonly name: string;
+  /**
+   * Start the harness. Throw `AgentUnavailableError` when it cannot run
+   * here — no SDK, no binary, no key — which is an ordinary state of a
+   * healthy machine, and the view shows the `fallback`.
+   */
+  start(host: DriverHost): Promise<DriverSession>;
+}
+
+/** The harness cannot run here. Not a bug: the view shows its `fallback`. */
+export class AgentUnavailableError extends Error {
+  override readonly name = 'AgentUnavailableError';
+}

package/src/core/index.ts

@@ -0,0 +1,54 @@
+// `@windowkit/agent-chat/core`: the session, the message model, the driver
+// seam and the tool helpers. No React, and no renderer: a DOM or terminal
+// front end can drive the same session.
+
+export {
+  createAgentSession,
+  describeRenderers,
+  type AgentOptions,
+  type AgentSession,
+  type CoreToolSetting,
+  type SessionSnapshot,
+} from './session.js';
+export {
+  AgentUnavailableError,
+  type AgentDriver,
+  type ApprovalResult,
+  type DriverConfig,
+  type DriverEvent,
+  type DriverHost,
+  type DriverSession,
+  type GateDecision,
+  type OutgoingMessage,
+} from './driver.js';
+export {
+  defineTool,
+  errorResult,
+  isStandardSchema,
+  jsonSchemaOf,
+  normalizeResult,
+  validateInput,
+  type AnyToolDef,
+  type InferInput,
+  type JsonObjectSchema,
+  type StandardSchemaLike,
+  type ToolContext,
+  type ToolDef,
+  type ToolParameters,
+  type ToolRenderInfo,
+  type ToolResult,
+} from './tools.js';
+export {
+  reduce,
+  restore,
+  findLivePart,
+  findPart,
+  type TranscriptAction,
+} from './reducer.js';
+export { categoryOf, policyDecision } from './policy.js';
+export {
+  messageMarkdown,
+  sourceLabel,
+  transcriptMarkdown,
+} from './markdown.js';
+export * from './types.js';

package/src/core/markdown.ts

@@ -0,0 +1,56 @@
+// A transcript as markdown: what Copy puts on the clipboard, and what an app
+// saves. Text is written as the agent wrote it; a tool call is one line,
+// since its output is the harness's and usually long.
+
+import type { AgentMessage, MessageSource, Part } from './types.js';
+
+/** What a message's author is called: a peer's name, or its id; a
+ *  channel's server. */
+export function sourceLabel(from: MessageSource): string {
+  return from.kind === 'peer' ? from.name || from.id : from.server;
+}
+
+export function messageMarkdown(message: AgentMessage): string {
+  return message.parts.map(partMarkdown).filter(Boolean).join('\n\n');
+}
+
+export function transcriptMarkdown(messages: readonly AgentMessage[]): string {
+  return messages
+    .map((m) => {
+      const body = messageMarkdown(m);
+      if (!body) return '';
+      if (m.role !== 'user') return body;
+      const who = m.from ? `From ${sourceLabel(m.from)}` : 'You';
+      return `**${who}:**\n\n${body}`;
+    })
+    .filter(Boolean)
+    .join('\n\n---\n\n');
+}
+
+function partMarkdown(part: Part): string {
+  switch (part.type) {
+    case 'text':
+      return part.text;
+    case 'reasoning':
+      return '';
+    case 'tool':
+      return `> ${part.title}${part.state === 'done' ? '' : ` (${part.state})`}`;
+    case 'plan':
+      return part.entries
+        .map((e) => `- [${e.status === 'completed' ? 'x' : ' '}] ${e.text}`)
+        .join('\n');
+    case 'question':
+      return part.questions
+        .map((q) => {
+          const a = part.answers?.[q.question];
+          return a ? `> ${q.question}\n>\n> ${a}` : `> ${q.question}`;
+        })
+        .join('\n\n');
+    case 'file':
+      return `[${part.label}]`;
+    case 'notice':
+      return `_${part.text}_`;
+    case 'data':
+      return '';
+  }
+}

package/src/core/policy.ts

@@ -0,0 +1,77 @@
+// The permission policy: what runs without asking, before the app's
+// `onToolCall` has had a say. Pure, so the table below is the whole story.
+
+import type { DriverConfig, GateDecision } from './driver.js';
+import type { CoreToolKey, ToolCall, ToolKind } from './types.js';
+
+/** The `coreTools` category a tool kind belongs to. */
+export function categoryOf(kind: ToolKind): CoreToolKey | undefined {
+  switch (kind) {
+    case 'execute':
+      return 'shell';
+    case 'read':
+    case 'search':
+      return 'read';
+    case 'edit':
+    case 'delete':
+    case 'move':
+      return 'edit';
+    case 'fetch':
+      return 'web';
+    default:
+      return undefined;
+  }
+}
+
+const READS: ReadonlySet<ToolKind> = new Set(['read', 'search', 'think']);
+const EDITS: ReadonlySet<ToolKind> = new Set(['edit', 'move']);
+
+/**
+ * | policy        | reads | edits | anything else |
+ * | ------------- | ----- | ----- | ------------- |
+ * | `'ask'`       | run   | ask   | ask           |
+ * | `'edits'`     | run   | run   | ask           |
+ * | `'read-only'` | run   | deny  | deny          |
+ * | `'auto'`      | the harness decides                 |
+ *
+ * Over all of it: an app tool runs unless its `ask` says otherwise, a
+ * category or name in `coreTools` set to `'ask'` always asks, and one set to
+ * `false` that a harness could not remove is denied.
+ */
+export function policyDecision(
+  call: ToolCall,
+  config: DriverConfig,
+): GateDecision {
+  const category = categoryOf(call.kind);
+  const named = (list: readonly string[]) =>
+    list.includes(call.label) ||
+    (!call.app && !!category && list.includes(category));
+
+  if (named(config.removed)) {
+    return { behavior: 'deny', message: `${call.label} is turned off here.` };
+  }
+  if (call.app) {
+    const tool = config.tools.get(call.label);
+    return tool?.ask ? { behavior: 'ask' } : { behavior: 'allow' };
+  }
+  if (named(config.asking)) return { behavior: 'ask' };
+
+  switch (config.permissions) {
+    case 'auto':
+      return { behavior: 'defer' };
+    case 'read-only':
+      return READS.has(call.kind)
+        ? { behavior: 'allow' }
+        : {
+            behavior: 'deny',
+            message: 'This session is read-only: nothing may be changed.',
+          };
+    case 'edits':
+      return READS.has(call.kind) || EDITS.has(call.kind)
+        ? { behavior: 'allow' }
+        : { behavior: 'ask' };
+    case 'ask':
+    default:
+      return READS.has(call.kind) ? { behavior: 'allow' } : { behavior: 'ask' };
+  }
+}