@windowkit/agent-chat 0.0.0-stage → 0.1.0

package/src/drivers/claude/input.ts

@@ -0,0 +1,47 @@
+// An async iterable fed by `push`: the SDK's streaming input, which is read
+// for the life of the session and ends when the session closes.
+
+export class InputQueue<T> implements AsyncIterable<T> {
+  #items: T[] = [];
+  #waiting: ((r: IteratorResult<T>) => void) | null = null;
+  #ended = false;
+
+  push(item: T): void {
+    if (this.#ended) throw new Error('The session is closed.');
+    if (this.#waiting) {
+      const resolve = this.#waiting;
+      this.#waiting = null;
+      resolve({ value: item, done: false });
+    } else {
+      this.#items.push(item);
+    }
+  }
+
+  end(): void {
+    this.#ended = true;
+    if (this.#waiting) {
+      const resolve = this.#waiting;
+      this.#waiting = null;
+      resolve({ value: undefined, done: true });
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: () => {
+        const item = this.#items.shift();
+        if (item !== undefined)
+          return Promise.resolve({ value: item, done: false });
+        if (this.#ended)
+          return Promise.resolve({ value: undefined, done: true });
+        return new Promise((resolve) => {
+          this.#waiting = resolve;
+        });
+      },
+      return: () => {
+        this.end();
+        return Promise.resolve({ value: undefined, done: true });
+      },
+    };
+  }
+}

package/src/drivers/claude/peers.ts

@@ -0,0 +1,153 @@
+// Messages that are not the user's, in Claude Code's own terms.
+//
+// Claude Code tells who wrote a user turn by its `origin`. A host that types
+// for the user says `{ kind: 'human' }`: a turn with no origin is
+// unattributed, and fails closed where Claude Code asks whether a human
+// said it. A message from another session is `{ kind: 'peer', from }`, its
+// text wrapped in the envelope Claude Code itself writes for one — so the
+// model reads it as reported speech from that session, which is how Claude
+// Desktop hands a session its peers' messages. And what Claude Code takes
+// from another session or an MCP channel comes back out with its origin, the
+// envelope still on its text.
+//
+// The envelope's shape is Claude Code 2.1's, read from what it accepts: the
+// attributes in this order, each held to the characters it allows, and the
+// body on lines of its own.
+
+import type { MessageSource, PeerSource } from '../../core/types.js';
+import type { SdkMessage } from './sdk.js';
+
+const PEER_TAG = 'cross-session-message';
+const CHANNEL_TAG = 'channel';
+
+/** `from` keeps to these characters; anything else is percent-encoded, as
+ *  Claude Code encodes the ids it makes. */
+const ID_UNSAFE = /[^A-Za-z0-9:_/.\\-]/gu;
+const ID_MAX = 300;
+const SESSION_ID = /^[A-Za-z0-9_-]{1,80}$/;
+const NAME_MAX = 64;
+
+/** The origin a turn is sent with: the user's, or a peer's. */
+export function originOf(
+  from: PeerSource | undefined,
+): Record<string, unknown> {
+  if (!from) return { kind: 'human' };
+  const name = nameOf(from.name);
+  return {
+    kind: 'peer',
+    from: idOf(from.id),
+    ...(name ? { name } : {}),
+    ...(from.session && SESSION_ID.test(from.session)
+      ? { fromSession: from.session }
+      : {}),
+  };
+}
+
+/** A peer's message, wrapped as Claude Code wraps one. */
+export function peerEnvelope(from: PeerSource, body: string): string {
+  const attrs = [`from="${idOf(from.id)}"`];
+  if (from.session && SESSION_ID.test(from.session)) {
+    attrs.push(`from-session="${from.session}"`);
+  }
+  const name = nameOf(from.name);
+  if (name) attrs.push(`from-name="${name}"`);
+  // a body cannot close the envelope it is in
+  const safe = body.replace(new RegExp(`<\\/?(?=${PEER_TAG})`, 'gi'), '<\\');
+  return `<${PEER_TAG} ${attrs.join(' ')}>\n${safe}\n</${PEER_TAG}>`;
+}
+
+/**
+ * A user turn Claude Code took from someone other than the user — another
+ * session, a channel — as the session draws it. `null` for anything else:
+ * the user's own turns, tool results, a subagent's input.
+ */
+export function incomingOf(
+  m: SdkMessage,
+): { text: string; from: MessageSource } | null {
+  if (m.parent_tool_use_id) return null;
+  const origin = m.origin as Record<string, unknown> | undefined;
+  if (!origin || (origin.kind !== 'peer' && origin.kind !== 'channel')) {
+    return null;
+  }
+  const text = textOf(
+    (m.message as { content?: unknown } | undefined)?.content,
+  );
+  if (text === null) return null;
+  if (origin.kind === 'channel') {
+    const server = typeof origin.server === 'string' ? origin.server : '';
+    const body = unwrap(text, CHANNEL_TAG);
+    return body.trim()
+      ? { text: body, from: { kind: 'channel', server } }
+      : null;
+  }
+  const body =
+    typeof origin.body === 'string' ? origin.body : unwrap(text, PEER_TAG);
+  if (!body.trim()) return null;
+  const id = typeof origin.from === 'string' ? decode(origin.from) : 'unknown';
+  return {
+    text: body,
+    from: {
+      kind: 'peer',
+      id,
+      ...(typeof origin.name === 'string' && origin.name
+        ? { name: origin.name }
+        : {}),
+      ...(typeof origin.fromSession === 'string'
+        ? { session: origin.fromSession }
+        : {}),
+    },
+  };
+}
+
+function idOf(id: string): string {
+  const bytes = new TextEncoder();
+  const encoded = id.replace(ID_UNSAFE, (c) =>
+    Array.from(
+      bytes.encode(c),
+      (b) => `%${b.toString(16).toUpperCase().padStart(2, '0')}`,
+    ).join(''),
+  );
+  // a cut must not leave half an escape
+  return (encoded || 'app').slice(0, ID_MAX).replace(/%[0-9A-F]?$/, '');
+}
+
+function nameOf(name: string | undefined): string {
+  if (!name) return '';
+  const clean = name
+    .replace(/["<>]/g, '')
+    // control, format and separator characters: what Claude Code strips
+    .replace(/[\p{Cc}\p{Cf}\p{Cs}\p{Zl}\p{Zp}]/gu, '')
+    .trim();
+  return [...clean].slice(0, NAME_MAX).join('');
+}
+
+function decode(id: string): string {
+  try {
+    return decodeURIComponent(id);
+  } catch {
+    return id;
+  }
+}
+
+/** The text of a turn's content, or `null` when it is not text alone. */
+function textOf(content: unknown): string | null {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return null;
+  const texts: string[] = [];
+  for (const block of content as Array<Record<string, unknown>>) {
+    if (block.type === 'text' && typeof block.text === 'string') {
+      texts.push(block.text);
+    } else if (block.type === 'tool_result') {
+      return null;
+    }
+  }
+  return texts.length ? texts.join('\n') : null;
+}
+
+/** What is inside `<tag …>…</tag>`, when that is the whole of the text. */
+function unwrap(text: string, tag: string): string {
+  const match = new RegExp(
+    `^\\s*<${tag}(?:\\s[^>]*)?>\\n?([\\s\\S]*?)\\n?</${tag}>\\s*$`,
+  ).exec(text);
+  return match ? match[1]!.trim() : text;
+}

package/src/drivers/claude/schema.ts

@@ -0,0 +1,99 @@
+// A tool's parameters as the zod shape the SDK's `tool()` takes.
+//
+// A zod object is handed over by its `shape`. A JSON Schema is translated:
+// the subset tool arguments use — objects, strings, numbers, integers,
+// booleans, arrays, enums, constants, nullable unions — with `description`
+// carried, and anything else as `unknown`, which the model still sees the
+// description of and the tool's own validation still checks.
+
+import { isStandardSchema, type ToolParameters } from '../../core/tools.js';
+import type { ZodLike, ZodTypeLike } from './sdk.js';
+
+export function zodShapeOf(
+  parameters: ToolParameters,
+): Record<string, unknown> | null {
+  if (isStandardSchema(parameters)) {
+    const shape = (parameters as { shape?: unknown }).shape;
+    if (shape && typeof shape === 'object')
+      return shape as Record<string, unknown>;
+    return null;
+  }
+  return null;
+}
+
+export function shapeFromJsonSchema(
+  schema: Record<string, unknown>,
+  z: ZodLike,
+): Record<string, ZodTypeLike> {
+  const properties = (schema.properties ?? {}) as Record<
+    string,
+    Record<string, unknown>
+  >;
+  const required = new Set((schema.required as string[] | undefined) ?? []);
+  const shape: Record<string, ZodTypeLike> = {};
+  for (const [key, prop] of Object.entries(properties)) {
+    const type = typeOf(prop, z);
+    shape[key] = required.has(key) ? type : type.optional();
+  }
+  return shape;
+}
+
+function typeOf(schema: Record<string, unknown>, z: ZodLike): ZodTypeLike {
+  let t = baseType(schema, z);
+  if (typeof schema.description === 'string')
+    t = t.describe(schema.description);
+  return t;
+}
+
+function baseType(schema: Record<string, unknown>, z: ZodLike): ZodTypeLike {
+  if (
+    Array.isArray(schema.enum) &&
+    schema.enum.every((v) => typeof v === 'string')
+  ) {
+    const values = schema.enum as string[];
+    if (values.length) return z.enum(values as [string, ...string[]]);
+  }
+  if ('const' in schema) {
+    const v = schema.const;
+    if (v === null || ['string', 'number', 'boolean'].includes(typeof v)) {
+      return z.literal(v as string | number | boolean | null);
+    }
+  }
+  const types = Array.isArray(schema.type)
+    ? (schema.type as string[])
+    : [schema.type];
+  const nonNull = types.filter((t) => t !== 'null');
+  const nullable = nonNull.length < types.length;
+  const one =
+    nonNull.length === 1 ? single(nonNull[0], schema, z) : z.unknown();
+  return nullable ? z.union([one, z.null()]) : one;
+}
+
+function single(
+  type: unknown,
+  schema: Record<string, unknown>,
+  z: ZodLike,
+): ZodTypeLike {
+  switch (type) {
+    case 'string':
+      return z.string();
+    case 'number':
+      return z.number();
+    case 'integer':
+      return z.number().int();
+    case 'boolean':
+      return z.boolean();
+    case 'array':
+      return z.array(
+        schema.items && typeof schema.items === 'object'
+          ? typeOf(schema.items as Record<string, unknown>, z)
+          : z.unknown(),
+      );
+    case 'object':
+      return schema.properties
+        ? z.object(shapeFromJsonSchema(schema, z))
+        : z.record(z.string(), z.unknown());
+    default:
+      return z.unknown();
+  }
+}

package/src/drivers/claude/sdk.ts

@@ -0,0 +1,138 @@
+// The slice of `@anthropic-ai/claude-agent-sdk` this driver uses, written out
+// structurally, and the loader that reaches it.
+//
+// Two reasons it is not an `import type` from the package. The SDK is an
+// optional peer — some 200 MB with its native binary — and an `import type`
+// would put it in the type graph, so an app that never installed it could no
+// longer type-check against this package. And tests hand the driver a fake
+// SDK, which is all a structural type asks of them.
+
+import { AgentUnavailableError } from '../../core/driver.js';
+import type { ToolResult } from '../../core/tools.js';
+
+/** One user turn, as streaming input takes it. */
+export interface SdkUserMessage {
+  type: 'user';
+  message: {
+    role: 'user';
+    content: string | Array<Record<string, unknown>>;
+  };
+  parent_tool_use_id: null;
+  priority?: 'now' | 'next' | 'later';
+  /** Who wrote it: `{ kind: 'human' }` for the user, a peer's for another
+   *  session (`peers.ts`). */
+  origin?: Record<string, unknown>;
+  /** Delivered as written: no `@path` expansion, no slash commands. */
+  client_composed?: true;
+}
+
+/** What the query yields. Read loosely: the union grows every month. */
+export interface SdkMessage {
+  type: string;
+  subtype?: string;
+  [key: string]: unknown;
+}
+
+export interface SdkQuery extends AsyncIterable<SdkMessage> {
+  interrupt(): Promise<unknown>;
+  setPermissionMode?(mode: string): Promise<void>;
+  setModel?(model?: string): Promise<void>;
+  supportedModels?(): Promise<
+    Array<{ value: string; displayName: string; description?: string }>
+  >;
+  supportedCommands?(): Promise<Array<{ name: string; description?: string }>>;
+  close?(): void;
+}
+
+export type SdkToolHandler = (
+  args: Record<string, unknown>,
+  extra: unknown,
+) => Promise<ToolResult>;
+
+export interface ClaudeSdk {
+  query(args: {
+    prompt: AsyncIterable<SdkUserMessage>;
+    options?: Record<string, unknown>;
+  }): SdkQuery;
+  tool(
+    name: string,
+    description: string,
+    inputSchema: Record<string, unknown>,
+    handler: SdkToolHandler,
+  ): unknown;
+  createSdkMcpServer(options: {
+    name: string;
+    version?: string;
+    tools?: unknown[];
+  }): unknown;
+}
+
+export const CLAUDE_SDK = '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * The SDK, or `AgentUnavailableError` saying what is wrong: not installed —
+ * with the line that installs it — or installed and failing to load, with
+ * the reason. A missing package the SDK itself needs is the second kind, not
+ * the first: telling someone who has just installed the SDK to install it
+ * sends them round in a circle.
+ */
+export async function loadClaudeSdk(
+  specifier: string = CLAUDE_SDK,
+): Promise<ClaudeSdk> {
+  try {
+    // The specifier is a variable so neither the compiler nor a bundler
+    // follows it: the package is an optional peer.
+    return (await import(specifier)) as ClaudeSdk;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = (err as { code?: unknown } | null)?.code;
+    const missing =
+      (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') &&
+      message.includes(`'${specifier}'`);
+    throw new AgentUnavailableError(
+      missing
+        ? `The Claude Agent SDK is not installed. Install it beside this ` +
+            `package: npm install ${specifier}`
+        : `The Claude Agent SDK is installed but did not load: ${message}`,
+    );
+  }
+}
+
+/**
+ * Zod, for the SDK's in-process tools: `tool()` takes a zod shape. An app
+ * whose parameters are zod already hands its own over; a JSON Schema is
+ * turned into one with the zod the SDK brought (a peer of the SDK, so
+ * installed beside it).
+ */
+export interface ZodLike {
+  string(): ZodTypeLike;
+  number(): ZodTypeLike & { int(): ZodTypeLike };
+  boolean(): ZodTypeLike;
+  array(item: ZodTypeLike): ZodTypeLike;
+  object(shape: Record<string, ZodTypeLike>): ZodTypeLike;
+  enum(values: [string, ...string[]]): ZodTypeLike;
+  unknown(): ZodTypeLike;
+  record(key: ZodTypeLike, value: ZodTypeLike): ZodTypeLike;
+  union(options: [ZodTypeLike, ZodTypeLike, ...ZodTypeLike[]]): ZodTypeLike;
+  literal(value: string | number | boolean | null): ZodTypeLike;
+  null(): ZodTypeLike;
+}
+
+export interface ZodTypeLike {
+  optional(): ZodTypeLike;
+  describe(description: string): ZodTypeLike;
+}
+
+export async function loadZod(): Promise<ZodLike> {
+  try {
+    const name: string = 'zod';
+    const mod = (await import(name)) as { z?: ZodLike } & ZodLike;
+    return mod.z ?? mod;
+  } catch {
+    throw new Error(
+      'A tool with a JSON Schema needs zod to reach the Claude Agent SDK, ' +
+        'which installs it as a peer. Install zod, or define the parameters ' +
+        'with z.object().',
+    );
+  }
+}

package/src/drivers/claude/tools.ts

@@ -0,0 +1,141 @@
+// Claude Code's built-in tools: which `coreTools` category each is in, its
+// kind, and the one line its card shows.
+
+import type { CoreToolKey, ToolKind, ToolOutput } from '../../core/types.js';
+
+/** The built-ins each category names. A name Claude Code no longer has is
+ *  harmless in `disallowedTools`. */
+export const CATEGORY_TOOLS: Readonly<Record<CoreToolKey, readonly string[]>> =
+  {
+    shell: ['Bash', 'BashOutput', 'KillShell'],
+    read: ['Read', 'Glob', 'Grep', 'LS'],
+    edit: ['Edit', 'MultiEdit', 'Write', 'NotebookEdit'],
+    web: ['WebFetch', 'WebSearch'],
+    agents: ['Agent', 'Task'],
+    todos: ['TodoWrite', 'TaskCreate', 'TaskUpdate', 'TaskList', 'TaskGet'],
+  };
+
+/** The prefix in-process tools are named under: `mcp__app__openTicket`. */
+export const APP_SERVER = 'app';
+export const APP_PREFIX = `mcp__${APP_SERVER}__`;
+
+const KINDS: Readonly<Record<string, ToolKind>> = {
+  Bash: 'execute',
+  BashOutput: 'execute',
+  KillShell: 'execute',
+  Read: 'read',
+  LS: 'read',
+  NotebookRead: 'read',
+  Glob: 'search',
+  Grep: 'search',
+  Edit: 'edit',
+  MultiEdit: 'edit',
+  Write: 'edit',
+  NotebookEdit: 'edit',
+  WebFetch: 'fetch',
+  WebSearch: 'fetch',
+  Agent: 'think',
+  Task: 'think',
+  ExitPlanMode: 'think',
+};
+
+/** The tools this driver draws as something other than a tool card. */
+export const HIDDEN_TOOLS: ReadonlySet<string> = new Set([
+  'TodoWrite',
+  'AskUserQuestion',
+]);
+
+export function labelOf(name: string): string {
+  return name.startsWith(APP_PREFIX) ? name.slice(APP_PREFIX.length) : name;
+}
+
+export function isAppTool(name: string): boolean {
+  return name.startsWith(APP_PREFIX);
+}
+
+export function kindOf(name: string): ToolKind {
+  return KINDS[name] ?? 'other';
+}
+
+/** The card's line: `Read src/app.ts`, `make test`, `Fetch https://…`. */
+export function titleOf(name: string, input: unknown): string {
+  const label = labelOf(name);
+  const i = (input && typeof input === 'object' ? input : {}) as Record<
+    string,
+    unknown
+  >;
+  const s = (k: string) => (typeof i[k] === 'string' ? (i[k] as string) : '');
+  switch (name) {
+    case 'Bash':
+      return s('description') || firstLine(s('command')) || 'Bash';
+    case 'Read':
+    case 'Edit':
+    case 'MultiEdit':
+    case 'Write':
+      return s('file_path') ? `${name} ${s('file_path')}` : name;
+    case 'NotebookEdit':
+      return s('notebook_path') ? `${name} ${s('notebook_path')}` : name;
+    case 'Glob':
+      return s('pattern') ? `Find ${s('pattern')}` : name;
+    case 'Grep':
+      return s('pattern') ? `Search for ${s('pattern')}` : name;
+    case 'LS':
+      return s('path') ? `List ${s('path')}` : name;
+    case 'WebFetch':
+      return s('url') ? `Fetch ${s('url')}` : name;
+    case 'WebSearch':
+      return s('query') ? `Search the web for ${s('query')}` : name;
+    case 'Agent':
+    case 'Task':
+      return s('description') || 'Agent';
+    case 'ExitPlanMode':
+      return 'Approve the plan';
+    default:
+      return label;
+  }
+}
+
+/** What a finished built-in call shows, worked out from its input where the
+ *  input says more than the result: an edit is its diff. */
+export function outputOf(
+  name: string,
+  input: unknown,
+  resultText: string,
+  isError: boolean,
+): ToolOutput[] {
+  const i = (input && typeof input === 'object' ? input : {}) as Record<
+    string,
+    unknown
+  >;
+  if (!isError) {
+    if (name === 'Edit' && typeof i.file_path === 'string') {
+      return [
+        {
+          type: 'diff',
+          path: i.file_path,
+          oldText: String(i.old_string ?? ''),
+          newText: String(i.new_string ?? ''),
+        },
+      ];
+    }
+    if (name === 'Write' && typeof i.file_path === 'string') {
+      return [
+        {
+          type: 'diff',
+          path: i.file_path,
+          oldText: null,
+          newText: String(i.content ?? ''),
+        },
+      ];
+    }
+  }
+  if (!resultText) return [];
+  if (kindOf(name) === 'execute')
+    return [{ type: 'terminal', text: resultText }];
+  return [{ type: 'text', text: resultText }];
+}
+
+function firstLine(text: string): string {
+  const line = text.split('\n')[0] ?? '';
+  return line.length > 120 ? `${line.slice(0, 117)}…` : line;
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// `@windowkit/agent-chat`: `<AgentChat>` and the hooks around it, with the
+// core's types and helpers re-exported, so an app imports from one place.
+//
+// The drivers are not re-exported: each is its own subpath
+// (`/drivers/claude`), loaded when a session starts, so a bundle carries the
+// one it uses.
+
+export {
+  AgentChat,
+  type AgentChatProps,
+  type AgentChatViewProps,
+} from './view/AgentChat.js';
+export { useAgent, useSessionSnapshot } from './view/use-agent.js';
+export type { ComposerOptions } from './view/Composer.js';
+export {
+  copyCode,
+  defineTool,
+  type CodeAction,
+  type CodeActionContext,
+  type ComponentEntry,
+  type FenceEntry,
+  type FenceInfo,
+  type ToolRenderer,
+} from './view/types.js';
+export { splitFences, type Segment } from './view/fences.js';
+
+export {
+  AgentUnavailableError,
+  categoryOf,
+  createAgentSession,
+  describeRenderers,
+  messageMarkdown,
+  sourceLabel,
+  transcriptMarkdown,
+  type AgentDriver,
+  type AgentOptions,
+  type AgentSession,
+  type AnyToolDef,
+  type CoreToolSetting,
+  type DriverConfig,
+  type DriverEvent,
+  type DriverHost,
+  type DriverSession,
+  type SessionSnapshot,
+  type ToolContext,
+  type ToolDef,
+  type ToolParameters,
+  type ToolRenderInfo,
+  type ToolResult,
+} from './core/index.js';
+export type * from './core/types.js';