experimental-a2 0.11.0 → 0.13.0

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>
+  )
+}

package/examples/playground/app/agent/compaction-settings.test.ts

@@ -0,0 +1,128 @@
+import { expect, it } from 'vitest'
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { memory } from 'experimental-a2/store-memory'
+import { compactionOptions, demoAgent, latestCompactionSettings } from './model'
+import { updateCompactionSettings } from './compaction-settings'
+
+const request = (
+  settings: unknown,
+  options: { origin?: string; contentType?: string; id?: string } = {},
+): Request =>
+  new Request('https://example.test/agent/session/compaction', {
+    method: 'POST',
+    headers: {
+      origin: options.origin ?? 'https://example.test',
+      'content-type': options.contentType ?? 'application/json',
+    },
+    body: JSON.stringify({ id: options.id ?? crypto.randomUUID(), settings }),
+  })
+
+it('uses the request Host when Next normalizes the internal URL', async () => {
+  let writes = 0
+  const response = await updateCompactionSettings({
+    request: new Request('http://localhost:3107/agent/s/compaction', {
+      method: 'POST',
+      headers: {
+        host: '127.0.0.1:3107',
+        origin: 'http://127.0.0.1:3107',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        id: crypto.randomUUID(),
+        settings: { mode: 'manual', thresholdTokens: 1 },
+      }),
+    }),
+    sessionId: 's',
+    append: async () => {
+      writes += 1
+    },
+  })
+  expect(response.status).toBe(200)
+  expect(writes).toBe(1)
+})
+
+it('saves session settings durably and idempotently without starting a turn', async () => {
+  let generations = 0
+  const server = createAgentServer({
+    agent: demoAgent,
+    store: memory(),
+    model: 'test/model',
+    compaction: ({ history }) => compactionOptions(history),
+    generate: () => {
+      generations += 1
+      return new ReadableStream({
+        start(controller) {
+          controller.close()
+        },
+      })
+    },
+  })
+  const session = server.session('settings-test')
+  const id = crypto.randomUUID()
+  const save = () =>
+    updateCompactionSettings({
+      request: request({ mode: 'manual', thresholdTokens: 1 }, { id }),
+      sessionId: session.id,
+      append: (event) => session.append(event),
+    })
+  expect((await save()).status).toBe(200)
+  expect((await save()).status).toBe(200)
+  await server.drain(session.id)
+  const history = await session.history()
+  expect(history.map((event) => event.type)).toEqual([
+    'compaction.settings.updated',
+  ])
+  expect(latestCompactionSettings(history).settings).toEqual({
+    mode: 'manual',
+    thresholdTokens: 1,
+  })
+  expect(compactionOptions(history)).toEqual({ thresholdTokens: 1 })
+  expect(compactionOptions(await server.session('other').history())).toEqual({})
+  expect(generations).toBe(0)
+
+  await updateCompactionSettings({
+    request: request({ mode: 'disabled' }),
+    sessionId: session.id,
+    append: (event) => session.append(event),
+  })
+  expect(compactionOptions(await session.history())).toBe(false)
+  await updateCompactionSettings({
+    request: request({ mode: 'automatic' }),
+    sessionId: session.id,
+    append: (event) => session.append(event),
+  })
+  expect(compactionOptions(await session.history())).toEqual({})
+})
+
+it.each([0, -1, 1.5, Number.MAX_SAFE_INTEGER + 1, '1', null])(
+  'rejects invalid threshold %s',
+  async (thresholdTokens) => {
+    let writes = 0
+    const response = await updateCompactionSettings({
+      request: request({ mode: 'manual', thresholdTokens }),
+      sessionId: 's',
+      append: async () => {
+        writes += 1
+      },
+    })
+    expect(response.status).toBe(400)
+    expect(writes).toBe(0)
+  },
+)
+
+it.each([
+  { origin: 'https://other.test', status: 403 },
+  { contentType: 'text/plain', status: 415 },
+  { id: 'not-an-id', status: 400 },
+])('rejects invalid request boundaries %j', async ({ status, ...options }) => {
+  let writes = 0
+  const response = await updateCompactionSettings({
+    request: request({ mode: 'automatic' }, options),
+    sessionId: 's',
+    append: async () => {
+      writes += 1
+    },
+  })
+  expect(response.status).toBe(status)
+  expect(writes).toBe(0)
+})

package/examples/playground/app/agent/compaction-settings.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod'
+import { compactionSettingsSchema, type CompactionSettings } from './model'
+
+const updateSchema = z.strictObject({
+  id: z.uuid(),
+  settings: compactionSettingsSchema,
+})
+
+export async function updateCompactionSettings(options: {
+  request: Request
+  sessionId: string
+  append: (event: {
+    id: string
+    type: 'compaction.settings.updated'
+    payload: CompactionSettings
+  }) => Promise<unknown>
+}): Promise<Response> {
+  const { request, sessionId } = options
+  const origin = request.headers.get('origin')
+  const requestUrl = new URL(request.url)
+  requestUrl.host = request.headers.get('host') ?? requestUrl.host
+  if (origin !== null && origin !== requestUrl.origin) {
+    return Response.json(
+      { error: 'Use this page to update compaction settings.' },
+      { status: 403 },
+    )
+  }
+  if (
+    request.headers.get('content-type')?.split(';')[0]?.trim() !==
+    'application/json'
+  ) {
+    return Response.json({ error: 'Expected JSON settings.' }, { status: 415 })
+  }
+  if (sessionId.length === 0)
+    return Response.json({ error: 'Session is required.' }, { status: 400 })
+  const parsed = updateSchema.safeParse(await request.json().catch(() => null))
+  if (!parsed.success) {
+    return Response.json(
+      { error: 'Choose a mode and a positive whole-number threshold.' },
+      { status: 400 },
+    )
+  }
+  await options.append({
+    id: `agent.compaction.settings:${encodeURIComponent(sessionId)}:${parsed.data.id}`,
+    type: 'compaction.settings.updated',
+    payload: parsed.data.settings,
+  })
+  return Response.json({ settings: parsed.data.settings })
+}