@windowkit/agent-chat 0.3.0 → 0.4.0

package/src/drivers/claude/results.ts

@@ -0,0 +1,252 @@
+// What Claude Code's structured tool results say beyond their text.
+//
+// A tool's result reaches the client twice: as the `tool_result` block the
+// model reads, and as the user message's `tool_use_result`, the tool's own
+// output object (typed `unknown` by the SDK; the shapes here are its
+// `sdk-tools.d.ts`). The text is what a card shows. The object is where the
+// rest is: the task list's changes, the pull request a command opened, the
+// page the agent published, the files it sent, the pixels of an image.
+
+import type {
+  ArtifactData,
+  AttachmentsData,
+  PlanEntry,
+  PullRequestData,
+  SessionLinkData,
+  ToolOutput,
+} from '../../core/types.js';
+
+type Obj = Record<string, unknown>;
+
+const obj = (v: unknown): Obj | undefined =>
+  v && typeof v === 'object' && !Array.isArray(v) ? (v as Obj) : undefined;
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v !== '' ? v : undefined;
+const num = (v: unknown): number | undefined =>
+  typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+
+/** The tools whose calls are the plan, not cards. */
+export const TASK_TOOLS: ReadonlySet<string> = new Set([
+  'TaskCreate',
+  'TaskUpdate',
+  'TaskList',
+  'TaskGet',
+]);
+
+type Status = PlanEntry['status'];
+const statusOf = (v: unknown): Status | undefined =>
+  v === 'pending' || v === 'in_progress' || v === 'completed' ? v : undefined;
+
+/**
+ * Claude Code's task list, as the fold of every `TaskCreate` and
+ * `TaskUpdate` this session saw, corrected by what `TaskList` and `TaskGet`
+ * report. It lives as long as the session: a task made in one turn is
+ * updated in the next.
+ */
+export class TaskFold {
+  readonly #tasks = new Map<string, { subject: string; status: Status }>();
+
+  /** Fold one finished call in. True if the list changed. */
+  apply(name: string, input: unknown, result: unknown): boolean {
+    const i = obj(input) ?? {};
+    const r = obj(result) ?? {};
+    switch (name) {
+      case 'TaskCreate': {
+        const task = obj(r.task);
+        const id = str(task?.id);
+        const subject = str(task?.subject) ?? str(i.subject);
+        if (!id || !subject) return false;
+        this.#tasks.set(id, { subject, status: 'pending' });
+        return true;
+      }
+      case 'TaskUpdate': {
+        if (r.success === false) return false;
+        const id = str(r.taskId) ?? str(i.taskId);
+        if (!id) return false;
+        if (i.status === 'deleted') return this.#tasks.delete(id);
+        const known = this.#tasks.get(id);
+        const subject = str(i.subject) ?? known?.subject;
+        // a task from before this session, named by nothing here
+        if (!subject) return false;
+        const status =
+          statusOf(obj(r.statusChange)?.to) ??
+          statusOf(i.status) ??
+          known?.status ??
+          'pending';
+        if (known && known.subject === subject && known.status === status) {
+          return false;
+        }
+        this.#tasks.set(id, { subject, status });
+        return true;
+      }
+      case 'TaskList': {
+        if (!Array.isArray(r.tasks)) return false;
+        const before = JSON.stringify(this.entries());
+        this.#tasks.clear();
+        for (const t of r.tasks as unknown[]) {
+          const task = obj(t);
+          const id = str(task?.id);
+          const subject = str(task?.subject);
+          if (id && subject) {
+            this.#tasks.set(id, {
+              subject,
+              status: statusOf(task?.status) ?? 'pending',
+            });
+          }
+        }
+        return JSON.stringify(this.entries()) !== before;
+      }
+      case 'TaskGet': {
+        const task = obj(r.task);
+        const id = str(task?.id);
+        const subject = str(task?.subject);
+        if (!id || !subject) return false;
+        const status = statusOf(task?.status) ?? 'pending';
+        const known = this.#tasks.get(id);
+        if (known && known.subject === subject && known.status === status) {
+          return false;
+        }
+        this.#tasks.set(id, { subject, status });
+        return true;
+      }
+    }
+    return false;
+  }
+
+  entries(): PlanEntry[] {
+    return [...this.#tasks.values()].map((t) => ({
+      text: t.subject,
+      status: t.status,
+    }));
+  }
+}
+
+/** A data part a finished call's result is worth, besides its card. */
+export type ResultData =
+  | { name: 'pull-request'; key: string; value: PullRequestData }
+  | { name: 'session'; key: string; value: SessionLinkData }
+  | { name: 'artifact'; key: string; value: ArtifactData }
+  | { name: 'attachments'; key: string; value: AttachmentsData };
+
+export function dataOf(
+  name: string,
+  input: unknown,
+  result: unknown,
+): ResultData[] {
+  const r = obj(result);
+  if (!r) return [];
+  const i = obj(input) ?? {};
+  switch (name) {
+    case 'Bash': {
+      const pr = obj(obj(r.gitOperation)?.pr);
+      const number = num(pr?.number);
+      if (!pr || number === undefined) return [];
+      const url = str(pr.url);
+      return [
+        {
+          name: 'pull-request',
+          key: 'pr',
+          value: {
+            number,
+            ...(url ? { url } : {}),
+            action: str(pr.action) ?? 'created',
+          },
+        },
+      ];
+    }
+    case 'Agent':
+    case 'Task':
+    case 'Workflow': {
+      const url = str(r.sessionUrl);
+      if (!url) return [];
+      const title = str(r.description) ?? str(i.description);
+      return [
+        {
+          name: 'session',
+          key: 'session',
+          value: { url, ...(title ? { title } : {}) },
+        },
+      ];
+    }
+    case 'Artifact': {
+      // a publish: list, read and the rest return other shapes
+      const url = str(r.url);
+      const path = str(r.path);
+      if (!url || !path) return [];
+      const title = str(r.title);
+      return [
+        {
+          name: 'artifact',
+          key: 'artifact',
+          value: { url, path, ...(title ? { title } : {}) },
+        },
+      ];
+    }
+    case 'SendUserFile': {
+      if (!Array.isArray(r.attachments)) return [];
+      const files = (r.attachments as unknown[]).flatMap((a) => {
+        const f = obj(a);
+        const path = str(f?.path);
+        if (!f || !path) return [];
+        const size = num(f.size);
+        const mime = str(f.media_type);
+        return [
+          {
+            path,
+            ...(size !== undefined ? { size } : {}),
+            ...(mime ? { mime } : {}),
+            isImage: f.isImage === true || !!mime?.startsWith('image/'),
+          },
+        ];
+      });
+      if (!files.length) return [];
+      const caption = str(r.caption) ?? str(i.caption);
+      return [
+        {
+          name: 'attachments',
+          key: 'files',
+          value: { files, ...(caption ? { caption } : {}) },
+        },
+      ];
+    }
+  }
+  return [];
+}
+
+/**
+ * The images a result carries: `image` blocks in the `tool_result` (an MCP
+ * tool's screenshot), or else Read's own of an image file.
+ */
+export function imagesOf(content: unknown, result: unknown): ToolOutput[] {
+  const out: ToolOutput[] = [];
+  if (Array.isArray(content)) {
+    for (const c of content as unknown[]) {
+      const block = obj(c);
+      if (block?.type !== 'image') continue;
+      const source = obj(block.source);
+      const data = str(source?.data);
+      if (source?.type !== 'base64' || !data) continue;
+      out.push({
+        type: 'image',
+        mime: str(source.media_type) ?? 'image/png',
+        data,
+      });
+    }
+  }
+  if (out.length) return out;
+  const r = obj(result);
+  const file = obj(r?.file);
+  const data = str(file?.base64);
+  if (r?.type !== 'image' || !file || !data) return [];
+  const dims = obj(file.dimensions);
+  const width = num(dims?.displayWidth) ?? num(dims?.originalWidth);
+  const height = num(dims?.displayHeight) ?? num(dims?.originalHeight);
+  return [
+    {
+      type: 'image',
+      mime: str(file.type) ?? 'image/png',
+      data,
+      ...(width !== undefined && height !== undefined ? { width, height } : {}),
+    },
+  ];
+}

package/src/drivers/claude/tools.ts

@@ -39,9 +39,15 @@ const KINDS: Readonly<Record<string, ToolKind>> = {
   ExitPlanMode: 'think',
 };
 
-/** The tools this driver draws as something other than a tool card. */
+/** The tools this driver draws as something other than a tool card: the
+ *  plan (`TodoWrite`, and the task tools Claude Code plans with now) and the
+ *  question card. */
 export const HIDDEN_TOOLS: ReadonlySet<string> = new Set([
   'TodoWrite',
+  'TaskCreate',
+  'TaskUpdate',
+  'TaskList',
+  'TaskGet',
   'AskUserQuestion',
 ]);
 

package/src/view/AgentChat.tsx

@@ -7,7 +7,13 @@
 // `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 {
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
 import type { StyleProp } from 'react-x11';
 
 import {
@@ -21,6 +27,7 @@ import { Composer, type ComposerOptions } from './Composer.js';
 import {
   ChatContext,
   componentMap,
+  composerChannel,
   fenceMap,
   type ChatContextValue,
 } from './context.js';
@@ -126,6 +133,7 @@ function ChatView({
   const look = useLook();
   const { fences, components, renderTool, codeActions, onLink, fontSize } =
     view;
+  const [composer] = useState(composerChannel);
   const context = useMemo<ChatContextValue>(
     () => ({
       session,
@@ -135,8 +143,18 @@ function ChatView({
       codeActions: codeActions ?? [copyCode],
       onLink,
       fontSize,
+      composer,
     }),
-    [session, fences, components, renderTool, codeActions, onLink, fontSize],
+    [
+      session,
+      fences,
+      components,
+      renderTool,
+      codeActions,
+      onLink,
+      fontSize,
+      composer,
+    ],
   );
 
   if (snap.status === 'unavailable' && view.fallback !== undefined) {

package/src/view/ArtifactCard.tsx

@@ -0,0 +1,18 @@
+// A page the agent published: the Artifact tool's `url`, `title` and the
+// file it came from.
+
+import type { ReactElement } from 'react';
+
+import type { ArtifactData } from '../core/types.js';
+import { LinkCard, shortUrl } from './LinkCard.js';
+
+export function ArtifactCard({ value }: { value: ArtifactData }): ReactElement {
+  return (
+    <LinkCard
+      kind="Published"
+      title={value.title ?? value.path ?? shortUrl(value.url)}
+      detail={[value.path, shortUrl(value.url)].filter(Boolean).join(' · ')}
+      href={value.url}
+    />
+  );
+}

package/src/view/AttachmentCard.tsx

@@ -0,0 +1,103 @@
+// Files the agent sent the user (`SendUserFile`): an image is drawn, read
+// from where the agent left it; any other file is a row with its size and,
+// where the app takes links, an Open button with its `file:` URL.
+
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { ReactElement } from 'react';
+import { Button } from 'react-x11';
+
+import type { AttachmentsData } from '../core/types.js';
+import { useChat } from './context.js';
+import { ImageView } from './ImageView.js';
+import { useLook } from './look.js';
+import { useSessionSnapshot } from './use-agent.js';
+
+export function AttachmentCard({
+  value,
+}: {
+  value: AttachmentsData;
+}): ReactElement {
+  const { session, onLink } = useChat();
+  const cwd = useSessionSnapshot(session).info.cwd;
+  const look = useLook();
+  return (
+    <box
+      style={{
+        flexDirection: 'column',
+        gap: look.gap,
+        padding: look.inset,
+        borderWidth: 1,
+        borderColor: look.border,
+        borderRadius: look.radius,
+      }}
+      aria-label="Attachments"
+    >
+      {value.caption ? (
+        <text style={{ color: look.text }}>{value.caption}</text>
+      ) : null}
+      {value.files.map((f, i) => {
+        const name = path.basename(f.path);
+        if (f.isImage) {
+          return (
+            <box key={i} style={{ flexDirection: 'column', gap: 2 }}>
+              <ImageView
+                source={cwd ? { path: f.path, cwd } : { path: f.path }}
+                alt={name}
+              />
+              <text style={{ color: look.muted, fontSize: look.smallSize }}>
+                {[name, sizeOf(f.size)].filter(Boolean).join(' · ')}
+              </text>
+            </box>
+          );
+        }
+        const full = cwd ? path.resolve(cwd, f.path) : f.path;
+        return (
+          <box
+            key={i}
+            style={{
+              flexDirection: 'row',
+              alignItems: 'center',
+              gap: look.gap,
+            }}
+          >
+            <text style={{ color: look.text, flexShrink: 1, maxLines: 1 }}>
+              {name}
+            </text>
+            <text
+              style={{
+                color: look.muted,
+                fontSize: look.smallSize,
+                flexGrow: 1,
+              }}
+            >
+              {sizeOf(f.size)}
+            </text>
+            {onLink && path.isAbsolute(full) ? (
+              <Button
+                size="small"
+                variant="ghost"
+                label="Open"
+                onPress={() => onLink(pathToFileURL(full).href)}
+              />
+            ) : null}
+          </box>
+        );
+      })}
+    </box>
+  );
+}
+
+/** `2 KB`, `1.4 MB`. */
+export function sizeOf(bytes: number | undefined): string {
+  if (bytes === undefined) return '';
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ['KB', 'MB', 'GB'];
+  let n = bytes / 1024;
+  let u = 0;
+  while (n >= 1024 && u < units.length - 1) {
+    n /= 1024;
+    u++;
+  }
+  return `${n < 10 ? n.toFixed(1).replace(/\.0$/, '') : Math.round(n)} ${units[u]}`;
+}

package/src/view/Composer.tsx

@@ -59,11 +59,20 @@ export function Composer({
   autoFocus,
   options = {},
 }: ComposerProps): ReactElement {
-  const { session } = useChat();
+  const { session, composer } = useChat();
   const snap = useSessionSnapshot(session);
   const look = useLook();
   const editor = useRef<RichTextEditorHandle | null>(null);
 
+  // a suggested reply, put in the box to edit or send
+  useEffect(() => {
+    composer.attach((text) => {
+      editor.current?.setValue(text);
+      editor.current?.focus();
+    });
+    return () => composer.attach(null);
+  }, [composer]);
+
   const busy =
     snap.status === 'running' ||
     snap.status === 'waiting' ||

package/src/view/DataPartView.tsx

@@ -0,0 +1,40 @@
+// A data part, drawn by its name. The names are the ones this package's
+// drivers write (`DataValues`); a part named anything else, or with a value
+// that is not the shape its name says, draws nothing.
+
+import type { ReactElement } from 'react';
+
+import type { DataPart, DataValues } from '../core/types.js';
+import { ArtifactCard } from './ArtifactCard.js';
+import { AttachmentCard } from './AttachmentCard.js';
+import { PullRequestCard } from './PullRequestCard.js';
+import { SessionCard } from './SessionCard.js';
+
+export function DataPartView({
+  part,
+}: {
+  part: DataPart;
+}): ReactElement | null {
+  const v = part.value as Record<string, unknown> | null | undefined;
+  if (!v || typeof v !== 'object') return null;
+  switch (part.name) {
+    case 'pull-request':
+      return typeof v.number === 'number' && typeof v.action === 'string' ? (
+        <PullRequestCard value={v as unknown as DataValues['pull-request']} />
+      ) : null;
+    case 'session':
+      return typeof v.url === 'string' ? (
+        <SessionCard value={v as unknown as DataValues['session']} />
+      ) : null;
+    case 'artifact':
+      return typeof v.url === 'string' ? (
+        <ArtifactCard value={v as unknown as DataValues['artifact']} />
+      ) : null;
+    case 'attachments':
+      return Array.isArray(v.files) ? (
+        <AttachmentCard value={v as unknown as DataValues['attachments']} />
+      ) : null;
+    default:
+      return null;
+  }
+}

package/src/view/ImageView.tsx

@@ -0,0 +1,64 @@
+// An image the agent read, a tool returned, or the user pasted: base64
+// bytes, or a file on this machine. No taller than the look says, never
+// wider than the space on offer, and in its own proportions.
+//
+// A format this runtime cannot decode (GIF under Node) draws nothing, as a
+// missing file does; `alt` is still what a screen reader says.
+
+import path from 'node:path';
+import { useMemo, type ReactElement } from 'react';
+
+import { useLook } from './look.js';
+
+export interface ImageViewProps {
+  /** base64 bytes, or a path, relative to `cwd` unless absolute. */
+  source: { data: string } | { path: string; cwd?: string };
+  /** Pixels, where known: drawn at that size, scaled down to fit. */
+  width?: number;
+  height?: number;
+  /** `look.imageHeight` unless said. */
+  maxHeight?: number;
+  alt: string;
+}
+
+export function ImageView({
+  source,
+  width,
+  height,
+  maxHeight,
+  alt,
+}: ImageViewProps): ReactElement {
+  const look = useLook();
+  const limit = maxHeight ?? look.imageHeight;
+  const data = 'data' in source ? source.data : undefined;
+  const file =
+    'path' in source
+      ? source.cwd
+        ? path.resolve(source.cwd, source.path)
+        : source.path
+      : undefined;
+  const src = useMemo(
+    () => (data !== undefined ? Buffer.from(data, 'base64') : file!),
+    [data, file],
+  );
+  const size =
+    width && height
+      ? (() => {
+          const scale = Math.min(1, limit / height);
+          return { width: width * scale, height: height * scale };
+        })()
+      : { maxHeight: limit };
+  return (
+    <image
+      src={src}
+      alt={alt}
+      style={{
+        ...size,
+        maxWidth: '100%',
+        objectFit: 'contain',
+        alignSelf: 'flex-start',
+        borderRadius: look.radius,
+      }}
+    />
+  );
+}

package/src/view/LinkCard.tsx

@@ -0,0 +1,99 @@
+// The frame every link card shares: what the link is, its title, where it
+// goes, and an Open button that hands the address to the app's `onLink`.
+// Without `onLink` there is no button — nothing here navigates by itself —
+// and the address is still there to read.
+
+import type { ReactElement } from 'react';
+import { Button } from 'react-x11';
+
+import { useChat } from './context.js';
+import { useLook } from './look.js';
+
+export interface LinkCardProps {
+  /** What kind of link: `Pull request`, `Session`, `Artifact`. */
+  kind: string;
+  title: string;
+  /** A line under the title: what happened, where it is. */
+  detail?: string;
+  /** Where Open goes. Absent: no button. */
+  href?: string;
+}
+
+export function LinkCard({
+  kind,
+  title,
+  detail,
+  href,
+}: LinkCardProps): ReactElement {
+  const { onLink } = useChat();
+  const look = useLook();
+  return (
+    <box
+      style={{
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: look.inset,
+        padding: look.inset,
+        borderWidth: 1,
+        borderColor: look.border,
+        borderRadius: look.radius,
+      }}
+      aria-label={`${kind}: ${title}`}
+    >
+      {/* the accent edge: a stripe, since a border of one side is square */}
+      <box
+        style={{
+          width: 3,
+          alignSelf: 'stretch',
+          borderRadius: 2,
+          backgroundColor: look.accent,
+        }}
+      />
+      <box
+        style={{
+          flexDirection: 'column',
+          gap: 2,
+          flexGrow: 1,
+          flexShrink: 1,
+        }}
+      >
+        <text
+          style={{
+            color: look.muted,
+            fontSize: look.smallSize,
+            fontWeight: 'bold',
+          }}
+        >
+          {kind.toUpperCase()}
+        </text>
+        <text style={{ color: look.text, fontWeight: 'bold', maxLines: 2 }}>
+          {title}
+        </text>
+        {detail ? (
+          <text
+            style={{
+              color: look.muted,
+              fontSize: look.captionSize,
+              maxLines: 1,
+            }}
+          >
+            {detail}
+          </text>
+        ) : null}
+      </box>
+      {href && onLink ? (
+        <Button
+          size="small"
+          variant="outline"
+          label="Open"
+          onPress={() => onLink(href)}
+        />
+      ) : null}
+    </box>
+  );
+}
+
+/** `github.com/o/r/pull/7` for `https://github.com/o/r/pull/7`. */
+export function shortUrl(href: string): string {
+  return href.replace(/^[a-z]+:\/\//i, '').replace(/\/$/, '');
+}