@windowkit/agent-chat 0.0.0-stage → 0.1.0

package/src/testing/fake.ts

@@ -0,0 +1,374 @@
+// A driver that plays a script: no harness, no key, no network.
+//
+// It goes through the real session — the gate, the policy, the approval
+// row, the app's tools — so a test of the UI tests what an app ships, and the
+// demo example runs on a machine with nothing installed.
+
+import type {
+  AgentDriver,
+  DriverEvent,
+  DriverHost,
+  DriverSession,
+  OutgoingMessage,
+} from '../core/driver.js';
+import {
+  NO_CAPABILITIES,
+  type Capabilities,
+  type MessageSource,
+  type Question,
+  type SessionInfo,
+  type ToolCall,
+  type ToolKind,
+  type ToolOutput,
+} from '../core/types.js';
+
+export type FakeStep =
+  | DriverEvent
+  /** Pause the script. */
+  | { type: 'wait'; ms: number }
+  /** Stream text in chunks of `chunk` characters, `delay` ms apart. */
+  | {
+      type: 'say';
+      text: string;
+      chunk?: number;
+      delay?: number;
+      reasoning?: boolean;
+    }
+  /**
+   * A tool call, through the gate: an app tool (one in `tools`) runs the
+   * app's function; any other ends with `result`.
+   */
+  | {
+      type: 'call';
+      id?: string;
+      name: string;
+      input?: unknown;
+      kind?: ToolKind;
+      title?: string;
+      result?: string | readonly ToolOutput[];
+      error?: string;
+    }
+  /** A question for the user; the script goes on once it is answered. */
+  | { type: 'ask'; id?: string; questions: readonly Question[] };
+
+export type FakeScript = (
+  message: OutgoingMessage,
+  turn: number,
+) =>
+  readonly FakeStep[] | Promise<readonly FakeStep[]> | AsyncIterable<FakeStep>;
+
+export interface FakeDriverOptions {
+  name?: string;
+  capabilities?: Partial<Capabilities>;
+  info?: Partial<SessionInfo>;
+  /** Throw this from `start`, as a harness that cannot run would. */
+  failStart?: Error;
+}
+
+export interface FakeDriver extends AgentDriver {
+  /** Every message the session sent. */
+  readonly sent: readonly OutgoingMessage[];
+  /** The host, once started. */
+  readonly host: DriverHost | null;
+  /** How many times `interrupt` was called. */
+  readonly interrupts: number;
+  /**
+   * A message from someone other than the user — another session, a
+   * channel — arriving as a harness reports one: the session draws it, and
+   * the script plays a turn for it after any turn under way, handed `from`
+   * where it is a peer.
+   */
+  receive(text: string, from: MessageSource): void;
+}
+
+const FAKE_CAPABILITIES: Capabilities = Object.freeze({
+  ...NO_CAPABILITIES,
+  tools: 'in-process',
+  systemPrompt: Object.freeze({ replace: true, append: true }),
+  coreTools: 'remove',
+  gate: 'every-call',
+}) as Capabilities;
+
+export function fakeDriver(
+  script: FakeScript,
+  options: FakeDriverOptions = {},
+): FakeDriver {
+  const sent: OutgoingMessage[] = [];
+  let host: DriverHost | null = null;
+  let interrupts = 0;
+  let take: ((text: string, from: MessageSource) => void) | null = null;
+  let received = 0;
+  const capabilities: Capabilities = {
+    ...FAKE_CAPABILITIES,
+    ...options.capabilities,
+  };
+
+  const driver: FakeDriver = {
+    name: options.name ?? 'fake',
+    get sent() {
+      return sent;
+    },
+    get host() {
+      return host;
+    },
+    get interrupts() {
+      return interrupts;
+    },
+    receive(text, from) {
+      if (!take) {
+        throw new Error('fakeDriver: receive() before the session started');
+      }
+      take(text, from);
+    },
+    async start(h) {
+      if (options.failStart) throw options.failStart;
+      host = h;
+      h.emit({
+        type: 'info',
+        info: {
+          agent: driver.name,
+          model: 'fake',
+          models: [],
+          ...options.info,
+        },
+      });
+      let turn = 0;
+      let running: AbortController | null = null;
+      let chain = Promise.resolve();
+
+      /** A turn for `message`, after the one under way. One that arrived
+       *  from elsewhere is reported as its turn begins, as a harness reports
+       *  a message when it takes it. */
+      const playTurn = (message: OutgoingMessage, arrived?: MessageSource) => {
+        const n = turn++;
+        chain = chain.then(async () => {
+          if (arrived) {
+            h.emit({
+              type: 'message',
+              id: message.id,
+              text: message.text,
+              from: arrived,
+            });
+          }
+          const abort = new AbortController();
+          running = abort;
+          try {
+            await play(h, script(message, n), n, abort.signal);
+            if (!abort.signal.aborted)
+              h.emit({ type: 'turn-end', reason: 'done' });
+          } catch (err) {
+            if (!abort.signal.aborted) {
+              h.emit({
+                type: 'turn-end',
+                reason: 'error',
+                error: err instanceof Error ? err.message : String(err),
+              });
+            }
+          } finally {
+            if (running === abort) running = null;
+          }
+        });
+      };
+      take = (text, from) =>
+        playTurn(
+          {
+            id: `r${++received}`,
+            text,
+            attachments: [],
+            steer: false,
+            ...(from.kind === 'peer' ? { from } : {}),
+          },
+          from,
+        );
+
+      const session: DriverSession = {
+        capabilities,
+        send(message) {
+          sent.push(message);
+          if (message.steer) return;
+          playTurn(message);
+        },
+        async interrupt() {
+          interrupts++;
+          running?.abort();
+        },
+        async setModel(id) {
+          h.emit({ type: 'info', info: { model: id } });
+        },
+        async setMode(id) {
+          h.emit({ type: 'info', info: { mode: id } });
+        },
+        async close() {
+          running?.abort();
+        },
+      };
+      return session;
+    },
+  };
+  return driver;
+}
+
+/** A script that answers turn `n` with `turns[n]`, and the last one after. */
+export function scripted(
+  ...turns: ReadonlyArray<readonly FakeStep[]>
+): FakeScript {
+  return (_message, n) => turns[Math.min(n, turns.length - 1)] ?? [];
+}
+
+async function play(
+  host: DriverHost,
+  steps: ReturnType<FakeScript>,
+  turn: number,
+  signal: AbortSignal,
+): Promise<void> {
+  const resolved = await steps;
+  let i = 0;
+  const iterable: Iterable<FakeStep> | AsyncIterable<FakeStep> =
+    Symbol.asyncIterator in (resolved as object)
+      ? (resolved as AsyncIterable<FakeStep>)
+      : (resolved as readonly FakeStep[]);
+  for await (const step of iterable) {
+    if (signal.aborted) return;
+    await run(host, step, `f${turn}:${i++}`, signal);
+  }
+}
+
+async function run(
+  host: DriverHost,
+  step: FakeStep,
+  key: string,
+  signal: AbortSignal,
+): Promise<void> {
+  switch (step.type) {
+    case 'wait':
+      await sleep(step.ms, signal);
+      return;
+    case 'say': {
+      const size = Math.max(1, step.chunk ?? step.text.length);
+      for (let at = 0; at < step.text.length; at += size) {
+        if (signal.aborted) return;
+        host.emit({
+          type: 'text',
+          id: key,
+          delta: step.text.slice(at, at + size),
+          ...(step.reasoning ? { reasoning: true } : {}),
+        });
+        await sleep(step.delay ?? 0, signal);
+      }
+      host.emit({
+        type: 'text',
+        id: key,
+        text: step.text,
+        done: true,
+        ...(step.reasoning ? { reasoning: true } : {}),
+      });
+      return;
+    }
+    case 'call':
+      await call(host, step, step.id ?? key, signal);
+      return;
+    case 'ask': {
+      await host.ask(step.id ?? key, step.questions, signal);
+      return;
+    }
+    default:
+      host.emit(step);
+  }
+}
+
+async function call(
+  host: DriverHost,
+  step: Extract<FakeStep, { type: 'call' }>,
+  id: string,
+  signal: AbortSignal,
+): Promise<void> {
+  const app = host.config.tools.has(step.name);
+  const def = app ? host.config.tools.get(step.name) : undefined;
+  const kind = step.kind ?? def?.kind ?? 'other';
+  const title =
+    step.title ??
+    (def?.title && step.input !== undefined
+      ? def.title(step.input)
+      : step.name);
+  host.emit({
+    type: 'tool-start',
+    id,
+    name: step.name,
+    label: step.name,
+    kind,
+    title,
+    input: step.input ?? {},
+    app,
+  });
+  const toolCall: ToolCall = {
+    id,
+    name: step.name,
+    label: step.name,
+    kind,
+    title,
+    input: step.input ?? {},
+    app,
+  };
+  const gate = await host.gate(toolCall);
+  let input: unknown = step.input ?? {};
+  if (gate.behavior === 'deny') {
+    host.emit({ type: 'tool-end', id, state: 'denied', error: gate.message });
+    return;
+  }
+  if (gate.behavior === 'allow' && gate.input !== undefined) input = gate.input;
+  if (gate.behavior === 'ask') {
+    const approval = await host.approve(toolCall, signal);
+    if (approval.behavior === 'deny') {
+      if (!signal.aborted) {
+        host.emit({
+          type: 'tool-end',
+          id,
+          state: 'denied',
+          error: approval.message,
+        });
+      }
+      return;
+    }
+    if (approval.input !== undefined) input = approval.input;
+  }
+  if (signal.aborted) return;
+  host.emit({ type: 'tool-update', id, state: 'running' });
+  if (app) {
+    const result = await host.runTool(step.name, input, { callId: id, signal });
+    if (signal.aborted) return;
+    const text = result.content
+      .map((c) => (c.type === 'text' ? c.text : ''))
+      .join('\n');
+    host.emit({
+      type: 'tool-end',
+      id,
+      state: result.isError ? 'error' : 'done',
+      ...(result.isError ? { error: text } : {}),
+    });
+    return;
+  }
+  if (step.error !== undefined) {
+    host.emit({ type: 'tool-end', id, state: 'error', error: step.error });
+    return;
+  }
+  const output: readonly ToolOutput[] =
+    typeof step.result === 'string'
+      ? [{ type: 'text', text: step.result }]
+      : (step.result ?? []);
+  host.emit({ type: 'tool-end', id, state: 'done', output });
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/testing/index.ts

@@ -0,0 +1,11 @@
+// `@windowkit/agent-chat/testing`: a driver that plays a script, for tests
+// and for demos with no harness installed.
+
+export {
+  fakeDriver,
+  scripted,
+  type FakeDriver,
+  type FakeDriverOptions,
+  type FakeScript,
+  type FakeStep,
+} from './fake.js';

package/src/view/AgentChat.tsx

@@ -0,0 +1,204 @@
+// `<AgentChat>`: a chat with a local agent harness.
+//
+// One element, one ladder. At the bottom, `<AgentChat agent="claude" />` is a
+// working chat. Each rung up is a prop: context (`cwd`, `instructions`,
+// `coreTools`), the app's own tools (`tools`), its renderers (`fences`,
+// `components`, `renderTool`), its interception (`codeActions`,
+// `onToolCall`). The top rung lifts the session out (`useAgent`, then
+// `session`) with the same options, moved rather than rewritten.
+
+import { useMemo, useRef, type ReactElement, type ReactNode } from 'react';
+import type { StyleProp } from 'react-x11';
+
+import {
+  describeRenderers,
+  type AgentOptions,
+  type AgentSession,
+  type SessionSnapshot,
+} from '../core/session.js';
+import type { ToolCall } from '../core/types.js';
+import { Composer, type ComposerOptions } from './Composer.js';
+import {
+  ChatContext,
+  componentMap,
+  fenceMap,
+  type ChatContextValue,
+} from './context.js';
+import { Header } from './Header.js';
+import { useLook } from './look.js';
+import { Transcript } from './Transcript.js';
+import {
+  copyCode,
+  type CodeAction,
+  type ComponentEntry,
+  type FenceEntry,
+  type ToolRenderer,
+} from './types.js';
+import { useAgent, useSessionSnapshot } from './use-agent.js';
+
+/** What the view takes, whoever owns the session. */
+export interface AgentChatViewProps {
+  /** Fenced blocks drawn by the app, by language. An entry with `describe`
+   *  also tells the agent the format exists. */
+  fences?: Readonly<Record<string, FenceEntry>>;
+  /** Components a reply may name as a tag on its own line. */
+  components?: Readonly<Record<string, ComponentEntry>>;
+  /** Tool calls drawn by the app, by the tool's label; `'*'` for the rest.
+   *  A tool's own `render` comes first. */
+  renderTool?: Readonly<Record<string, ToolRenderer>>;
+  /** Buttons on every fenced code block. Default `[copyCode]`. Nothing runs
+   *  a block unless an action here does. */
+  codeActions?: readonly CodeAction[];
+  /** A link in a reply was pressed. Nothing navigates by itself. */
+  onLink?: (href: string) => void;
+  placeholder?: string;
+  /** How the message box behaves: what it draws as markdown while typing,
+   *  the `@` file list, the `/` command list, pastes as attachments. */
+  composer?: ComposerOptions;
+  /** `true` for the session's line (agent, model, mode, cost, Copy), or a
+   *  function of the session for the app's own. Default `true`. */
+  header?: boolean | ((session: AgentSession) => ReactNode);
+  /** Shown while the transcript is empty. */
+  empty?: ReactNode;
+  /** Shown instead of the chat when the harness cannot run here. Default: a
+   *  line saying why. */
+  fallback?: ReactNode | ((snapshot: SessionSnapshot) => ReactNode);
+  /** Base text size. Default: the theme's. */
+  fontSize?: number;
+  autoFocus?: boolean;
+  style?: StyleProp;
+}
+
+type NoOptions = { readonly [K in keyof AgentOptions]?: never };
+
+/**
+ * Either the session's options — the chat owns its session — or a
+ * `session` from `useAgent`, and none of the options: they are the
+ * session's, and a chat handed one does not change it.
+ */
+export type AgentChatProps = AgentChatViewProps &
+  (
+    | (AgentOptions & { session?: undefined })
+    | (NoOptions & { session: AgentSession })
+  );
+
+export function AgentChat(props: AgentChatProps): ReactElement {
+  return props.session ? (
+    <ChatView session={props.session} view={props} />
+  ) : (
+    <OwnSession {...(props as AgentOptions & AgentChatViewProps)} />
+  );
+}
+
+function OwnSession(props: AgentOptions & AgentChatViewProps): ReactElement {
+  // Options are read once, but `onToolCall` is usually an inline arrow over
+  // the app's state: the session calls the latest one.
+  const latest = useRef(props);
+  latest.current = props;
+  const session = useAgent({
+    ...props,
+    instructions: [
+      ...(Array.isArray(props.instructions)
+        ? props.instructions
+        : props.instructions
+          ? [props.instructions as string]
+          : []),
+      ...describeRenderers({
+        fences: props.fences,
+        components: props.components,
+      }),
+    ],
+    ...(props.onToolCall
+      ? { onToolCall: (call: ToolCall) => latest.current.onToolCall?.(call) }
+      : {}),
+  });
+  return <ChatView session={session} view={props} />;
+}
+
+function ChatView({
+  session,
+  view,
+}: {
+  session: AgentSession;
+  view: AgentChatViewProps;
+}): ReactElement {
+  const snap = useSessionSnapshot(session);
+  const look = useLook();
+  const { fences, components, renderTool, codeActions, onLink, fontSize } =
+    view;
+  const context = useMemo<ChatContextValue>(
+    () => ({
+      session,
+      fences: fenceMap(fences),
+      components: componentMap(components),
+      renderTool: renderTool ?? {},
+      codeActions: codeActions ?? [copyCode],
+      onLink,
+      fontSize,
+    }),
+    [session, fences, components, renderTool, codeActions, onLink, fontSize],
+  );
+
+  if (snap.status === 'unavailable' && view.fallback !== undefined) {
+    return (
+      <box style={[{ flexDirection: 'column', flexGrow: 1 }, view.style]}>
+        {typeof view.fallback === 'function'
+          ? view.fallback(snap)
+          : view.fallback}
+      </box>
+    );
+  }
+
+  const header = view.header ?? true;
+  return (
+    <ChatContext.Provider value={context}>
+      <box
+        style={[
+          {
+            // fills what it is put in: the one-line usage needs no style
+            flexDirection: 'column',
+            flexGrow: 1,
+            flexShrink: 1,
+            minHeight: 0,
+            backgroundColor: look.background,
+          },
+          view.style,
+        ]}
+        data-testname="agent-chat"
+      >
+        {header === true ? (
+          <Header />
+        ) : typeof header === 'function' ? (
+          header(session)
+        ) : null}
+        {snap.status === 'unavailable' || snap.status === 'error' ? (
+          <box
+            style={{
+              padding: 10,
+              borderBottomWidth: 1,
+              borderBottomColor: look.border,
+            }}
+          >
+            <text
+              style={{
+                color: snap.status === 'error' ? look.danger : look.muted,
+              }}
+            >
+              {snap.error ?? 'The agent could not start.'}
+            </text>
+          </box>
+        ) : null}
+        <Transcript empty={view.empty} />
+        <Composer
+          {...(view.placeholder !== undefined
+            ? { placeholder: view.placeholder }
+            : {})}
+          {...(view.autoFocus !== undefined
+            ? { autoFocus: view.autoFocus }
+            : {})}
+          {...(view.composer ? { options: view.composer } : {})}
+        />
+      </box>
+    </ChatContext.Provider>
+  );
+}

package/src/view/CodeBlock.tsx

@@ -0,0 +1,108 @@
+// A fenced code block with a header of actions: Copy by default, and
+// whatever the app's `codeActions` add. Nothing here runs code; an action
+// that does is the app's.
+
+import { useEffect, useRef, useState, type ReactElement } from 'react';
+import { Button, useClipboard } from 'react-x11';
+import { Code } from '@react-x11/components/code';
+import type { FenceInfo } from '@react-x11/components/markdown';
+
+import type { AgentMessage } from '../core/types.js';
+import { useChat } from './context.js';
+import { useLook } from './look.js';
+import type { CodeAction, CodeActionContext } from './types.js';
+
+export interface CodeBlockProps {
+  fence: FenceInfo;
+  message: AgentMessage;
+}
+
+export function CodeBlock({ fence, message }: CodeBlockProps): ReactElement {
+  const { codeActions, session } = useChat();
+  const look = useLook();
+  const clipboard = useClipboard();
+  const [done, setDone] = useState<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  // an action on code still streaming in would act on half of it
+  const actions = fence.partial
+    ? []
+    : codeActions.filter((a) => !a.when || a.when(fence));
+
+  const run = (action: CodeAction) => {
+    const ctx: CodeActionContext = {
+      session,
+      message,
+      copy: (text) => clipboard.writeText(text),
+    };
+    Promise.resolve()
+      .then(() => action.run(fence, ctx))
+      .then(
+        () => {
+          if (!action.doneLabel) return;
+          setDone(action.id);
+          if (timer.current) clearTimeout(timer.current);
+          timer.current = setTimeout(() => setDone(null), 1500);
+        },
+        (err: unknown) =>
+          session.notify(
+            'error',
+            `${action.label} failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+      );
+  };
+
+  return (
+    <box
+      style={{
+        flexDirection: 'column',
+        borderWidth: 1,
+        borderColor: look.border,
+        borderRadius: 6,
+        overflow: 'hidden',
+      }}
+    >
+      <box
+        style={{
+          flexDirection: 'row',
+          alignItems: 'center',
+          gap: 4,
+          paddingLeft: 10,
+          paddingRight: 4,
+          minHeight: 26,
+          borderBottomWidth: 1,
+          borderBottomColor: look.border,
+        }}
+      >
+        <text style={{ color: look.muted, fontSize: 11, flexGrow: 1 }}>
+          {fence.lang || 'text'}
+        </text>
+        {actions.map((action) => (
+          <Button
+            key={action.id}
+            size="small"
+            variant="ghost"
+            label={
+              done === action.id
+                ? (action.doneLabel ?? action.label)
+                : action.label
+            }
+            onPress={() => run(action)}
+          />
+        ))}
+      </box>
+      <Code
+        source={fence.text}
+        {...(fence.lang ? { lang: fence.lang } : {})}
+        wrap
+        style={{ borderWidth: 0, borderRadius: 0 }}
+      />
+    </box>
+  );
+}