experimental-a2 0.12.0 → 0.14.0

package/examples/playground/app/agent/[agentId]/agent-queue.tsx

@@ -0,0 +1,289 @@
+'use client'
+
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import type { UIMessage } from 'ai'
+import type { InboxItem } from 'experimental-a2/ai'
+
+type QueueProps = {
+  items: InboxItem[]
+  paused: boolean
+  pendingEdits: readonly string[]
+  edit(message: UIMessage, revision: number): Promise<void>
+  move(inputId: string, beforeId: string | null): void
+  remove(inputId: string): Promise<void>
+  sendNow(inputId: string): Promise<void>
+}
+
+const queueIconPaths = {
+  edit: 'm15 5 4 4M4 20l4-1L20 7a2.8 2.8 0 0 0-4-4L4 15z',
+  up: 'm6 14 6-6 6 6',
+  down: 'm6 10 6 6 6-6',
+  remove: 'm6 6 12 12M6 18 18 6',
+  send: 'M4 12h15m-6-6 6 6-6 6',
+}
+
+function QueueIcon({ name }: { name: keyof typeof queueIconPaths }): ReactNode {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.7"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d={queueIconPaths[name]} />
+    </svg>
+  )
+}
+
+function QueuedInput({
+  item,
+  position,
+  count,
+  edit,
+  moveUp,
+  moveDown,
+  remove,
+  sendNow,
+  paused,
+  pendingEdit,
+}: {
+  item: InboxItem
+  position: number
+  count: number
+  edit: QueueProps['edit']
+  moveUp(): void
+  moveDown(): void
+  remove: QueueProps['remove']
+  sendNow: QueueProps['sendNow']
+  paused: boolean
+  pendingEdit: boolean
+}): ReactNode {
+  const [draft, setDraft] = useState<{ text: string; revision: number } | null>(
+    null,
+  )
+  const [pending, setPending] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const editButton = useRef<HTMLButtonElement>(null)
+  const restoreFocus = useRef(false)
+  useEffect(() => {
+    if (draft === null && !pending && !pendingEdit && restoreFocus.current) {
+      if (document.activeElement === document.body) editButton.current?.focus()
+      restoreFocus.current = false
+    }
+  }, [draft, pending, pendingEdit])
+  const text = item.message.parts
+    .filter((part) => part.type === 'text')
+    .map((part) => part.text)
+    .join('\n')
+  const cancel = (): void => {
+    restoreFocus.current = true
+    setDraft(null)
+    setError(null)
+  }
+  const perform = async (action: () => Promise<void>): Promise<void> => {
+    if (pending) return
+    setPending(true)
+    setError(null)
+    try {
+      await action()
+    } catch (failure) {
+      setError(failure instanceof Error ? failure.message : String(failure))
+    } finally {
+      setPending(false)
+    }
+  }
+  const save = async (): Promise<void> => {
+    if (!draft || pendingEdit || !draft.text.trim()) return
+    await perform(async () => {
+      await edit(
+        { ...item.message, parts: [{ type: 'text', text: draft.text }] },
+        draft.revision,
+      )
+      cancel()
+    })
+  }
+  return (
+    <li className={`agent-queue-item${draft ? ' editing' : ''}`}>
+      <div className="agent-queue-row">
+        <span
+          className="agent-queue-number"
+          aria-label={`Queue position ${position + 1}`}
+        >
+          {position + 1}
+        </span>
+        <p className="agent-queue-text" title={text}>
+          {text || 'Message'}
+        </p>
+        <div className="agent-queue-actions">
+          <button
+            type="button"
+            className="agent-queue-send"
+            title={
+              paused
+                ? 'Send next · waits for Resume while paused'
+                : 'Send after current step'
+            }
+            aria-label={`Send queued message ${position + 1} after current step`}
+            disabled={
+              pending ||
+              pendingEdit ||
+              draft !== null ||
+              item.message.role !== 'user'
+            }
+            onClick={() => void perform(() => sendNow(item.id))}
+          >
+            <QueueIcon name="send" />
+          </button>
+          <button
+            ref={editButton}
+            type="button"
+            title={
+              pendingEdit ? 'Waiting for edit confirmation' : 'Edit message'
+            }
+            aria-label={`Edit queued message ${position + 1}`}
+            aria-expanded={draft !== null}
+            disabled={pending || pendingEdit}
+            onClick={() =>
+              draft ? cancel() : setDraft({ text, revision: item.revision })
+            }
+          >
+            <QueueIcon name="edit" />
+          </button>
+          <button
+            type="button"
+            title="Move up"
+            aria-label={`Move queued message ${position + 1} up`}
+            disabled={position === 0 || pending}
+            onClick={moveUp}
+          >
+            <QueueIcon name="up" />
+          </button>
+          <button
+            type="button"
+            title="Move down"
+            aria-label={`Move queued message ${position + 1} down`}
+            disabled={position === count - 1 || pending}
+            onClick={moveDown}
+          >
+            <QueueIcon name="down" />
+          </button>
+          <button
+            type="button"
+            className="agent-queue-remove"
+            title="Remove from queue"
+            aria-label={`Remove queued message ${position + 1}`}
+            disabled={pending || draft !== null}
+            onClick={() => void perform(() => remove(item.id))}
+          >
+            <QueueIcon name="remove" />
+          </button>
+        </div>
+      </div>
+      {error ? (
+        <p className="error agent-queue-error" role="alert">
+          {error}
+        </p>
+      ) : null}
+      {draft ? (
+        <form
+          className="agent-queue-editor"
+          onSubmit={(event) => {
+            event.preventDefault()
+            void save()
+          }}
+        >
+          <textarea
+            autoFocus
+            aria-label={`Edit text for queued message ${position + 1}`}
+            rows={2}
+            value={draft.text}
+            disabled={pending}
+            onChange={(event) =>
+              setDraft({ ...draft, text: event.target.value })
+            }
+            onKeyDown={(event) => {
+              if (event.nativeEvent.isComposing) return
+              if (event.key === 'Escape' && !pending) {
+                event.preventDefault()
+                cancel()
+              }
+              if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+                event.preventDefault()
+                void save()
+              }
+            }}
+          />
+          <div className="agent-queue-editor-actions">
+            <span>⌘ / Ctrl + Enter to save</span>
+            <button
+              type="button"
+              className="secondary"
+              disabled={pending}
+              onClick={cancel}
+            >
+              Cancel
+            </button>
+            <button
+              type="submit"
+              disabled={pending || pendingEdit || !draft.text.trim()}
+            >
+              {pending ? 'Saving…' : 'Save'}
+            </button>
+          </div>
+        </form>
+      ) : null}
+    </li>
+  )
+}
+
+export function AgentQueue({
+  items,
+  paused,
+  pendingEdits,
+  edit,
+  move,
+  remove,
+  sendNow,
+}: QueueProps): ReactNode {
+  if (items.length === 0) return null
+  return (
+    <section className="agent-queue" aria-label="Queued messages">
+      <div className="agent-queue-header">
+        <h3>
+          Queued <span>{items.length}</span>
+        </h3>
+        <span className={`agent-queue-status${paused ? ' paused' : ''}`}>
+          {paused ? 'Paused' : 'Pending'}
+        </span>
+      </div>
+      <ol className="agent-queue-list">
+        {items.map((item, position) => (
+          <QueuedInput
+            key={item.id}
+            item={item}
+            position={position}
+            count={items.length}
+            edit={edit}
+            remove={remove}
+            sendNow={sendNow}
+            paused={paused}
+            pendingEdit={pendingEdits.includes(item.id)}
+            moveUp={() => {
+              const previous = items[position - 1]
+              if (previous) move(item.id, previous.id)
+            }}
+            moveDown={() => {
+              if (position < items.length - 1)
+                move(item.id, items[position + 2]?.id ?? null)
+            }}
+          />
+        ))}
+      </ol>
+    </section>
+  )
+}

package/examples/playground/app/agent/[agentId]/compaction/route.ts

@@ -0,0 +1,14 @@
+import { updateCompactionSettings } from '../../compaction-settings'
+import { agentServer } from '../../server'
+
+export async function POST(
+  request: Request,
+  context: { params: Promise<{ agentId: string }> },
+): Promise<Response> {
+  const { agentId } = await context.params
+  return updateCompactionSettings({
+    request,
+    sessionId: agentId,
+    append: (event) => agentServer.session(agentId).append(event),
+  })
+}

package/examples/playground/app/agent/[agentId]/compaction-event.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+import { formatActivityTime } from '@/app/components/activity-feed'
+import type { CompactionEntry } from '../compaction-timeline'
+
+export function CompactionEvent({
+  entry,
+}: {
+  entry: CompactionEntry
+}): ReactNode {
+  const { event, running, outcome } = entry
+  const completed = event.type === 'ai.compaction.completed'
+  const label = completed
+    ? 'Context compacted'
+    : running
+      ? 'Compacting…'
+      : 'Compaction did not complete'
+
+  return (
+    <details className="agent-compaction-event">
+      <summary>
+        <span role={running ? 'status' : undefined}>{label}</span>
+        <time dateTime={event.createdAt.toISOString()}>
+          {formatActivityTime(event.createdAt)}
+        </time>
+      </summary>
+      <p className="hint">
+        Event #{event.index} ·{' '}
+        {event.payload.throughIndex === undefined
+          ? `Through message ${event.payload.throughMessageId}`
+          : `Summarized through event #${event.payload.throughIndex}`}
+        {outcome === undefined ? null : ` · Generation ${outcome}`}
+      </p>
+      {completed && event.payload.summary ? (
+        <pre>{event.payload.summary}</pre>
+      ) : null}
+    </details>
+  )
+}

package/examples/playground/app/agent/[agentId]/compaction-panel.tsx

@@ -0,0 +1,294 @@
+'use client'
+
+import type { FormEvent, ReactNode } from 'react'
+import { useEffect, useId, useRef, useState } from 'react'
+import type { AIState } from 'experimental-a2/ai'
+import { formatActivityTime } from '@/app/components/activity-feed'
+import {
+  agentModel,
+  compactionSettingsSchema,
+  latestCompactionSettings,
+  type AgentEvent,
+  type CompactionSettings,
+} from '../model'
+
+const number = new Intl.NumberFormat('en-US')
+const tokens = (value: number | undefined): string =>
+  value === undefined
+    ? 'Not available'
+    : `${number.format(value)} ${value === 1 ? 'token' : 'tokens'}`
+
+function SettingsForm({
+  agentId,
+  settings,
+  closed,
+}: {
+  agentId: string
+  settings: CompactionSettings
+  closed: boolean
+}): ReactNode {
+  const modeId = useId()
+  const thresholdId = useId()
+  const [mode, setMode] = useState(settings.mode)
+  const [threshold, setThreshold] = useState(
+    settings.mode === 'manual' ? String(settings.thresholdTokens) : '',
+  )
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+  const pending = useRef<AbortController | null>(null)
+
+  useEffect(() => () => pending.current?.abort(), [])
+
+  const save = async (next: CompactionSettings): Promise<void> => {
+    pending.current?.abort()
+    const controller = new AbortController()
+    pending.current = controller
+    setSaving(true)
+    setError(null)
+    setNotice(null)
+    try {
+      const response = await fetch(
+        `/agent/${encodeURIComponent(agentId)}/compaction`,
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ id: crypto.randomUUID(), settings: next }),
+          signal: controller.signal,
+        },
+      )
+      if (!response.ok)
+        throw new Error('Could not save compaction settings. Try again.')
+      setNotice('Saved. The live feed will confirm the latest settings.')
+    } catch (cause) {
+      if (!controller.signal.aborted)
+        setError(cause instanceof Error ? cause.message : String(cause))
+    } finally {
+      if (pending.current === controller) {
+        pending.current = null
+        setSaving(false)
+      }
+    }
+  }
+
+  const submit = (event: FormEvent): void => {
+    event.preventDefault()
+    const parsed = compactionSettingsSchema.safeParse(
+      mode === 'manual'
+        ? { mode, thresholdTokens: Number(threshold) }
+        : { mode },
+    )
+    if (!parsed.success) {
+      setError('Enter a positive whole-number threshold.')
+      return
+    }
+    void save(parsed.data)
+  }
+
+  return (
+    <form className="compaction-form" onSubmit={submit}>
+      <fieldset disabled={saving || closed}>
+        <div className="compaction-fields">
+          <label htmlFor={modeId}>
+            Mode
+            <select
+              id={modeId}
+              value={mode}
+              onChange={(event) =>
+                setMode(event.target.value as CompactionSettings['mode'])
+              }
+            >
+              <option value="automatic">Automatic</option>
+              <option value="manual">Custom threshold</option>
+              <option value="disabled">Disable further compaction</option>
+            </select>
+          </label>
+          <label htmlFor={thresholdId}>
+            Threshold in tokens
+            <input
+              id={thresholdId}
+              type="number"
+              min={1}
+              max={Number.MAX_SAFE_INTEGER}
+              step={1}
+              required={mode === 'manual'}
+              disabled={mode !== 'manual'}
+              value={threshold}
+              onChange={(event) => setThreshold(event.target.value)}
+              placeholder="Automatic"
+            />
+          </label>
+        </div>
+        <div className="compaction-actions">
+          <button type="submit">{saving ? 'Saving…' : 'Apply settings'}</button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void save({ mode: 'manual', thresholdTokens: 1 })}
+          >
+            Set to 1 token
+          </button>
+          <button
+            type="button"
+            className="secondary"
+            onClick={() => void save({ mode: 'automatic' })}
+          >
+            Reset to automatic
+          </button>
+        </div>
+      </fieldset>
+      <p className="hint">
+        Changes apply to the next step that has not started and do not start a
+        new turn. Send a message to test. At 1 token, every eligible step
+        compacts until you reset it.
+      </p>
+      {mode === 'disabled' ? (
+        <p className="hint">
+          Existing summaries remain in use. This stops future compaction.
+        </p>
+      ) : null}
+      {notice ? (
+        <p role="status" className="hint">
+          {notice}
+        </p>
+      ) : null}
+      {error ? (
+        <p role="alert" className="error">
+          {error}
+        </p>
+      ) : null}
+    </form>
+  )
+}
+
+export function CompactionPanel({
+  agentId,
+  state,
+  events,
+}: {
+  agentId: string
+  state: AIState
+  events: readonly AgentEvent[]
+}): ReactNode {
+  const { settings, id } = latestCompactionSettings(events)
+  const metadata = state.modelMetadata[agentModel]
+  const limits = metadata?.status === 'resolved' ? metadata.limits : undefined
+  const automaticThreshold =
+    limits === undefined ? undefined : Math.floor(limits.contextWindow * 0.75)
+  const effectiveThreshold =
+    settings.mode === 'manual' ? settings.thresholdTokens : automaticThreshold
+  const lastStep = events.findLast(
+    (event) => event.type === 'ai.generation.completed',
+  )
+  const completed = events
+    .filter((event) => event.type === 'ai.compaction.completed')
+    .toReversed()
+  const compacting = state.compaction?.status === 'running'
+
+  return (
+    <details className="agent-compaction">
+      <summary>
+        <span className="compaction-chevron" aria-hidden="true">
+          ›
+        </span>
+        <strong>Compaction</strong>
+        <span className={`badge${compacting ? ' live' : ''}`}>
+          {compacting
+            ? 'Compacting…'
+            : settings.mode === 'disabled'
+              ? 'Disabled'
+              : settings.mode === 'manual'
+                ? `Custom · ${tokens(settings.thresholdTokens)}`
+                : 'Automatic'}
+        </span>
+      </summary>
+      <div className="compaction-controls">
+        <p className="hint">
+          Model: <code>{agentModel}</code>. Limits are saved for this session.
+        </p>
+        <dl className="compaction-metrics">
+          <div>
+            <dt>Context window</dt>
+            <dd>{tokens(limits?.contextWindow)}</dd>
+          </div>
+          <div>
+            <dt>Model output ceiling</dt>
+            <dd>{tokens(limits?.maxOutputTokens)}</dd>
+          </div>
+          <div>
+            <dt>Automatic trigger · 75%</dt>
+            <dd>{tokens(automaticThreshold)}</dd>
+          </div>
+          <div>
+            <dt>Threshold for next step</dt>
+            <dd>
+              {settings.mode === 'disabled'
+                ? 'Disabled'
+                : tokens(effectiveThreshold)}
+            </dd>
+          </div>
+          <div>
+            <dt>Last step input · reported</dt>
+            <dd>{tokens(lastStep?.payload.usage?.inputTokens)}</dd>
+          </div>
+          <div>
+            <dt>Last step input · estimated</dt>
+            <dd>{tokens(lastStep?.payload.inputTokenEstimate)}</dd>
+          </div>
+        </dl>
+        {limits === undefined ? (
+          <p className="hint">
+            {metadata?.status === 'unavailable'
+              ? 'Gateway did not report limits for this model. You can set a custom threshold.'
+              : metadata?.status === 'pending'
+                ? 'Model limits have been requested but are not resolved yet. The agent can continue.'
+                : 'Send a message to discover the model limits, or set a custom threshold first.'}
+          </p>
+        ) : null}
+        <SettingsForm
+          key={id}
+          agentId={agentId}
+          settings={settings}
+          closed={state.status === 'closed'}
+        />
+        <details className="compaction-history">
+          <summary>
+            Completed compactions <span>{completed.length}</span>
+          </summary>
+          {completed.length === 0 ? (
+            <p className="hint">
+              No completed compactions yet. Each completion will stay here after
+              reload.
+            </p>
+          ) : (
+            <ol>
+              {completed.map((event) => (
+                <li key={event.id}>
+                  <div className="compaction-marker">
+                    <strong>Context compacted · #{event.index}</strong>
+                    <time dateTime={event.createdAt.toISOString()}>
+                      {formatActivityTime(event.createdAt)}
+                    </time>
+                  </div>
+                  <p className="hint">
+                    {event.payload.throughIndex === undefined
+                      ? `Through message ${event.payload.throughMessageId}`
+                      : `Summarized through event #${event.payload.throughIndex}`}{' '}
+                    · {tokens(event.payload.usage?.inputTokens)} in ·{' '}
+                    {tokens(event.payload.usage?.outputTokens)} out
+                  </p>
+                  {event.payload.summary ? (
+                    <details>
+                      <summary>View summary</summary>
+                      <pre>{event.payload.summary}</pre>
+                    </details>
+                  ) : null}
+                </li>
+              ))}
+            </ol>
+          )}
+        </details>
+      </div>
+    </details>
+  )
+}