@xingular/harness 0.1.5 → 0.1.7

package/src/memory/proposals.ts

@@ -95,6 +95,8 @@ export interface Evidence {
   sourceText?: string | null
   /** Ids of the blocks attached to the run. */
   blocks?: string[]
+  runs?: Record<string, string>
+  sources?: Record<string, string>
 }
 
 const MIN_EXCERPT = 12
@@ -175,6 +177,7 @@ export function captureHashes(wiki: string): Map<string, string> {
   for (const page of store.loadPages(wiki)) add(page.frontmatter.id, page.path)
   for (const memory of facts.loadMemories(wiki)) add(memory.front.id, memory.path)
   for (const block of blocks.loadAll(wiki)) add(block.id, block.path)
+  for (const item of registry.list(dirname(wiki))) add(item.id, item.path)
   return hashes
 }
 
@@ -223,7 +226,11 @@ interface Write {
 }
 
 /** Validates proposals and applies the valid ones as one operation. Pure file logic. */
-export function apply(wiki: string, defaultNamespace: string, trigger: Trigger, proposals: ProposalSet, captured: ReadonlyMap<string, string>, evidence: Evidence): ApplyOutcome {
+export function apply(wiki: string, defaultNamespace: string, trigger: Trigger, proposals: ProposalSet, captured: ReadonlyMap<string, string>, evidence: Evidence, operationKey?: string, appliedBy?: string): ApplyOutcome {
+  if (operationKey) {
+    const committed = readJson<Operation>(join(operationsDir(wiki), `${safeId(operationKey)}.json`))
+    if (committed) return { operation: committed, parked: 0, flagged: 0, notes: ['This request was already applied.'] }
+  }
   const existing = store.loadPages(wiki)
   const existingMemories = facts.loadMemories(wiki)
   const root = dirname(wiki)
@@ -240,7 +247,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
   ])
   const outcome: ApplyOutcome = { operation: null, parked: 0, flagged: 0, notes: [] }
   const writes: Write[] = []
-  const actor = triggerActor(trigger)
+  const actor = appliedBy ?? triggerActor(trigger)
   const described = describeTrigger(trigger)
   const fromUser = trigger.kind === 'user'
 
@@ -248,7 +255,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
   const park = (kind: string, title: string, label: string, reason: string, body: string, entryId: string, payload: unknown): void => {
     outcome.parked += 1
     outcome.notes.push(`${label} went to the Inbox: ${reason}`)
-    inbox(wiki, kind, title, `${reason}\n\n${takeChars(body, 600)}`, [entryId], null, payload)
+    inbox(wiki, kind, title, `${reason}\n\n${takeChars(body, 600)}`, [entryId], null, operationKey && payload && typeof payload === 'object' ? { ...payload, curationJobId: operationKey } : payload)
   }
 
   // Evidence: a source in the Wiki, the triggering run, a URL, or the user's acceptance. A run
@@ -259,11 +266,12 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
     for (const reference of refs) {
       let id: string | null = null
       if (reference.kind === 'source') {
-        if (sourceIds.has(reference.ref) && (evidence.sourceText == null || quotedIn(evidence.sourceText, reference.excerpt))) id = reference.ref
+        const source = evidence.sources?.[reference.ref] ?? (trigger.kind === 'ingest' && trigger.sourceId === reference.ref ? evidence.sourceText : null)
+        if (sourceIds.has(reference.ref) && (operationKey ? quotedIn(source, reference.excerpt) : (evidence.sourceText == null || quotedIn(evidence.sourceText, reference.excerpt)))) id = reference.ref
       } else if (reference.kind === 'run') {
-        if (triggerRunId(trigger) === reference.ref && quotedIn(evidence.runText, reference.excerpt)) id = `run:${reference.ref}`
+        if (quotedIn(evidence.runs?.[reference.ref] ?? (triggerRunId(trigger) === reference.ref ? evidence.runText : null), reference.excerpt)) id = `run:${reference.ref}`
       } else if (reference.kind === 'url') {
-        if (reference.ref.startsWith('https://') || reference.ref.startsWith('http://')) id = `url:${reference.ref}`
+        if (!operationKey && (reference.ref.startsWith('https://') || reference.ref.startsWith('http://'))) id = `url:${reference.ref}`
       } else if (reference.kind === 'user') {
         if (fromUser) id = 'user:accepted'
       }
@@ -277,7 +285,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
       .filter((link) => knownIds.has(link.toId) || proposedIds.has(link.toId))
       .filter((link) => link.toId !== ownId)
       .map((link) => ({ fromId: ownId, toId: link.toId, type: link.type }))
-  const changedSince = (id: string, path: string): boolean => captured.has(id) && captured.get(id) !== fileHash(path)
+  const changedSince = (id: string, path: string): boolean => (captured.has(id) || Boolean(operationKey)) && captured.get(id) !== fileHash(path)
 
   for (const proposal of proposals.pages) {
     const pageId = store.slug(proposal.id ?? proposal.title)
@@ -464,7 +472,7 @@ export function apply(wiki: string, defaultNamespace: string, trigger: Trigger,
     }
   })
 
-  const operationId = newId()
+  const operationId = operationKey ?? newId()
   const short = operationId.slice(0, 8)
   const pages: OperationPage[] = writes.map((write) => ({
     pageId: write.entryId,

package/src/memory/recall.test.ts

@@ -87,6 +87,17 @@ test('an agent recalls its own chats by default and everything on request', () =
   expect(searchTool(env, { ...agent('agent-a'), runId: 'chat-1' }, { query: 'pnpm' })).not.toContain('run chat-1')
 })
 
+test('a caller cannot recall the conversations of agents its host excludes', () => {
+  const env = setup()
+  sync(env.root)
+  const caller = { ...agent('agent-a'), recallExcludeAgents: ['agent-b'] }
+  const all = searchTool(env, caller, { query: 'pnpm', scope: 'all' })
+  expect(all).toContain('chat-1')
+  expect(all).not.toContain('chat-2')
+  expect(() => readTool(env, caller, { run: 'chat-2' })).toThrow()
+  expect(readTool(env, agent('agent-a'), { run: 'chat-2' })).toContain('Plan the launch')
+})
+
 test('a session recalls only session runs of its project', () => {
   const env = setup()
   sync(env.root)

package/src/memory/recall.ts

@@ -221,6 +221,13 @@ export function sourceLabel(env: HarnessEnv, mode: string, sessionId: string, pr
   }
 }
 
+/** Whether a conversation belongs to an agent the caller may not recall. */
+function excluded(env: HarnessEnv, context: CallerContext, sessionId: string): boolean {
+  const hidden = context.recallExcludeAgents ?? []
+  if (!hidden.length) return false
+  return hidden.includes(sessionId) || hidden.includes(env.directory.sessionAgent(sessionId) ?? '')
+}
+
 /** `recall.search` as text for a model. */
 export function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string {
   const query = textParam(params, 'query')
@@ -229,7 +236,7 @@ export function searchTool(env: HarnessEnv, context: CallerContext, params: Para
   const requested = params?.limit
   const limit = typeof requested === 'number' && Number.isInteger(requested) && requested >= 0 ? requested : SEARCH_DEFAULT
   // The caller's current run is what it is in the middle of, not something to recall.
-  const hits = search(env.root, query, scope, limit + 4).filter((hit) => hit.runId !== context.runId).slice(0, Math.min(Math.max(limit, 1), SEARCH_MAX))
+  const hits = search(env.root, query, scope, limit + 4 + (context.recallExcludeAgents?.length ? SEARCH_MAX : 0)).filter((hit) => hit.runId !== context.runId && !excluded(env, context, hit.sessionId)).slice(0, Math.min(Math.max(limit, 1), SEARCH_MAX))
   if (!hits.length) {
     return scope.sessionId && !isSession(context) ? 'Nothing in your own conversations matches. Pass scope "all" to search every conversation and Harness run.' : 'Nothing in the recorded history matches.'
   }
@@ -242,7 +249,7 @@ export function readTool(env: HarnessEnv, context: CallerContext, params: Params
   const run = findRun(env.root, runId)
   if (!run) throw notFound('Run')
   // Reading is as wide as an "all" search for an agent, and as narrow as a search for a session.
-  if (!mayRead(callerScope(env.root, context, { scope: 'all' }), run)) throw notFound('Run')
+  if (!mayRead(callerScope(env.root, context, { scope: 'all' }), run) || excluded(env, context, run.sessionId)) throw notFound('Run')
   const messages = read(env.root, run.id)
   if (!messages.length) return 'That run has no recorded messages.'
   let text = `Run ${run.id} · ${run.startedAt.slice(0, 16)} · ${sourceLabel(env, run.mode, run.sessionId, run.projectId)} · ${run.status}\n`

package/src/server/methods.ts

@@ -14,7 +14,7 @@ import { capabilitySet } from '../capabilities/runSnapshot'
 import type { Harness } from '../harness'
 import * as blocks from '../memory/blocks'
 import { validateScopeIds } from '../mcp/connections'
-import type { CallerContext } from '../memory/caller'
+import { callerBlocks, type CallerContext } from '../memory/caller'
 import { dispatch } from '../memory/dispatch'
 import * as facts from '../memory/facts'
 import * as graph from '../memory/graph'
@@ -46,6 +46,16 @@ const text = (params: Params, name: string): string => {
   return value
 }
 const optional = (params: Params, name: string): string | null => (typeof params[name] === 'string' && params[name] ? (params[name] as string) : null)
+const questionAnswer = (value: unknown): { selected: string[]; text?: string; notes?: Record<string, string> } => {
+  const answer = value && typeof value === 'object' && !Array.isArray(value) ? value as Params : {}
+  return {
+    selected: Array.isArray(answer.selected) ? answer.selected.filter((label: unknown): label is string => typeof label === 'string') : [],
+    ...(typeof answer.text === 'string' && answer.text ? { text: answer.text } : {}),
+    ...(answer.notes && typeof answer.notes === 'object' && !Array.isArray(answer.notes)
+      ? { notes: Object.fromEntries(Object.entries(answer.notes).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) }
+      : {})
+  }
+}
 const pluginScope = (params: Params): plugins.PluginScope => ({ cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') })
 
 /** Sources larger than this are not imported. */
@@ -65,6 +75,14 @@ export function methods(harness: Harness): Record<string, Handler> {
     'harness.status': () => ({ dataRoot: harness.dataRoot, productName: env.productName, recovery: harness.recovery, activeRuns: runs.activeRunIds() }),
     'harness.open': (params: Params) => harness.open(text(params, 'dataRoot'), Array.isArray(params.agentIds) ? params.agentIds : []),
     'harness.rebuildIndex': () => harness.rebuildIndex(),
+    'maintenance.list': (params: Params) => maintenance.jobs().filter((job) => params.runId ? job.runId === params.runId || (Array.isArray(params.ids) && params.ids.includes(job.id)) : params.includeCompleted === true || !['completed', 'rejected'].includes(job.status)).map(({ prepared: _prepared, hashes: _hashes, ...job }) => job),
+    'maintenance.review': (params: Params) => { maintenance.enqueue({ kind: 'review', requestId: optional(params, 'requestId') ?? String(Date.now()), manual: params.manual === true }); return { queued: true } },
+    'maintenance.failRun': (params: Params) => { maintenance.finishRun(text(params, 'runId'), true); return null },
+    'maintenance.retry': (params: Params) => maintenance.retry(text(params, 'id')),
+    'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
+    'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
+    'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+    'hub.readDocument': (params: Params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version')),
 
     // ---- Accounts --------------------------------------------------------------------------------
     'accounts.list': () => accounts.overview(),
@@ -84,6 +102,7 @@ export function methods(harness: Harness): Record<string, Handler> {
     'accounts.sharedDir': () => ensureSharedDir(accounts.dir),
     'accounts.refresh': (params: Params) => accounts.refresh(optional(params, 'accountId')),
     'accounts.loginStart': (params: Params) => accounts.loginStart(text(params, 'accountId'), text(params, 'provider'), optional(params, 'method')),
+    'accounts.loginStatus': (params: Params) => accounts.loginStatus(text(params, 'accountId')),
     'accounts.loginRespond': (params: Params) => accounts.loginRespond(text(params, 'loginId'), text(params, 'promptId'), typeof params.value === 'string' ? params.value : null),
     'accounts.loginCancel': (params: Params) => accounts.loginCancel(text(params, 'accountId'), optional(params, 'loginId')),
     'accounts.setApiKey': (params: Params) => accounts.setApiKey(text(params, 'accountId'), text(params, 'key'), text(params, 'provider')),
@@ -196,6 +215,11 @@ export function methods(harness: Harness): Record<string, Handler> {
     },
 
     // ---- What a session calls, on behalf of a caller the host names -------------------------------
+    'memory.permissions': (params: Params) => {
+      const context = (params.context ?? {}) as CallerContext
+      const { caller, attached } = callerBlocks(env, context)
+      return attached.map((block) => ({ id: block.id, writable: blocks.editRefusal(caller, block) === null, reason: blocks.editRefusal(caller, block) }))
+    },
     'memory.call': (params: Params) => dispatch(env, (params.context ?? {}) as CallerContext, text(params, 'call'), params.params ?? {}),
 
     // ---- Recall ------------------------------------------------------------------------------------
@@ -278,6 +302,13 @@ export function methods(harness: Harness): Record<string, Handler> {
       await runs.interrupt(runId)
       return loadRun(root(), runId)
     },
+    // A message the person sends into a live reply. It reaches the model after the current step;
+    // `message.steered` marks the moment, and a message the run never takes is reported by its end.
+    'runs.steer': async (params: Params) => {
+      const runId = text(params, 'runId')
+      await runs.steer(runId, text(params, 'text'))
+      return { runId }
+    },
     // What the application reports into a live run, and an approval it asks a person for.
     'runs.emit': (params: Params) => {
       const run = runs.active(text(params, 'runId'))
@@ -298,7 +329,11 @@ export function methods(harness: Harness): Record<string, Handler> {
       return { decision }
     },
     'runs.resolveApproval': (params: Params) => runs.resolveApproval(text(params, 'runId'), text(params, 'approvalId'), params.decision),
-    'runs.answerQuestion': (params: Params) => runs.answerQuestion(text(params, 'runId'), text(params, 'questionId'), { selected: Array.isArray(params.answer?.selected) ? params.answer.selected : [], ...(typeof params.answer?.text === 'string' && params.answer.text ? { text: params.answer.text } : {}) }),
+    'runs.answerQuestion': (params: Params) => runs.answerQuestion(text(params, 'runId'), text(params, 'questionId'), questionAnswer(params.answer)),
+    'runs.answerQuestions': (params: Params) => {
+      if (!Array.isArray(params.answers)) throw invalid('answers must be an array.')
+      runs.answerQuestions(text(params, 'runId'), text(params, 'batchId'), params.answers.map((item: Params) => ({ questionId: text(item, 'questionId'), answer: questionAnswer(item.answer) })))
+    },
 
     // ---- Sessions ----------------------------------------------------------------------------------
     'sessions.run': (params: Params) => sessions.run(params as SessionRunInput),

package/src/sessions/contracts.ts

@@ -10,6 +10,7 @@ export const runEventTypeSchema = z.enum([
   'context.snapshot',
   'message.delta',
   'message.completed',
+  'message.steered',
   'tool.started',
   'tool.completed',
   'retry.started',
@@ -35,6 +36,8 @@ export type RunEventType = z.infer<typeof runEventTypeSchema>
 
 const messageDeltaPayload = z.object({ messageId: z.string(), text: z.string() })
 const messageCompletedPayload = z.object({ messageId: z.string(), role: z.enum(['user', 'assistant']), text: z.string() })
+/** A message the person sent into the run while it was going; the model reads it from its next request on. */
+const messageSteeredPayload = z.object({ text: z.string() })
 const contextSnapshotPayload = z.object({
   systemPrompt: z.string().max(100_000),
   contextUpdate: z.string().max(100_000).optional(),
@@ -96,15 +99,37 @@ const approvalRequestedPayload = z.object({
 const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() })
 export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional() })
 export type QuestionOption = z.infer<typeof questionOptionSchema>
+const questionBatchFields = {
+  batchId: z.string().min(1).optional(),
+  batchIndex: z.number().int().min(1).max(5).optional(),
+  batchCount: z.number().int().min(1).max(5).optional()
+}
+const questionBatchRefinement = <T extends { batchId?: string; batchIndex?: number; batchCount?: number }>(value: T, context: z.RefinementCtx): void => {
+  const fields = [value.batchId, value.batchIndex, value.batchCount]
+  if (fields.some((field) => field !== undefined) && fields.some((field) => field === undefined)) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch fields must be supplied together.' })
+  }
+  if (value.batchIndex !== undefined && value.batchCount !== undefined && value.batchIndex > value.batchCount) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch index cannot exceed its count.' })
+  }
+}
 const questionRequestedPayload = z.object({
   questionId: z.string(),
   question: z.string().min(1),
+  summary: z.string().min(1).max(100).optional(),
   options: z.array(questionOptionSchema),
   multiSelect: z.boolean(),
   allowText: z.boolean(),
-  userOnly: z.boolean().optional()
-})
-const questionAnsweredPayload = z.object({ questionId: z.string(), selected: z.array(z.string()), text: z.string().optional() })
+  userOnly: z.boolean().optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement)
+const questionAnsweredPayload = z.object({
+  questionId: z.string(),
+  selected: z.array(z.string()),
+  text: z.string().optional(),
+  notes: z.record(z.string(), z.string().max(10_000)).optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement)
 /** A short emoji sequence, never words or numbers. */
 const reactionAddedPayload = z.object({ emoji: z.string().min(1).refine((text) => Buffer.byteLength(text) <= 16 && !/[A-Za-z0-9\s]/.test(text)) })
 /** A message this run's agent sent to (`to`) or received back from (`from`) another agent. */
@@ -196,6 +221,7 @@ export const runEventPayloadSchemas = {
   'context.snapshot': contextSnapshotPayload,
   'message.delta': messageDeltaPayload,
   'message.completed': messageCompletedPayload,
+  'message.steered': messageSteeredPayload,
   'tool.started': toolPayload,
   'tool.completed': toolPayload,
   'retry.started': retryStartedPayload,

package/src/sessions/conversation.test.ts

@@ -147,4 +147,31 @@ describe('a whole reply, with a scripted model', () => {
     await until(() => settled(id))
     expect(model.lastToolResults().at(-1)).not.toContain('waiting in the Inbox')
   })
+
+  it('delivers a message sent during a tool call after that call, before the next request', async () => {
+    const { harness, model, call, start, until, settled, of } = await setup()
+    model.script([model.calls(['bash', { command: 'ls' }]), model.says('Noted.')])
+    const id = await start({ tools: { allow: ['read', 'bash'], gated: ['bash'] } })
+    await until(() => of(id).some((event) => event.type === 'approval.requested'))
+    const approval = of(id).find((event) => event.type === 'approval.requested')!.payload as { approvalId: string }
+    await call('runs.steer', { runId: id, text: 'Also check the logs.' })
+    harness.runs.resolveApproval(id, approval.approvalId, 'denied')
+    await until(() => settled(id))
+    const types = of(id).map((event) => event.type)
+    expect(of(id).find((event) => event.type === 'message.steered')?.payload).toEqual({ text: 'Also check the logs.' })
+    expect(types.indexOf('message.steered')).toBeGreaterThan(types.indexOf('approval.resolved'))
+    expect(model.requests()).toBe(2)
+    // The context update reaches the model as a user-role message too; the prompt and the steer come last.
+    expect(model.lastUserTexts().slice(-2)).toEqual(['Go.', 'Also check the logs.'])
+    expect(of(id).at(-1)?.type).toBe('completed')
+  })
+
+  it('refuses a message once the reply has ended, so the app sends it as a new reply', async () => {
+    const { call, model, start, until, settled, of } = await setup()
+    model.script([model.says('Done.')])
+    const id = await start()
+    await until(() => settled(id))
+    await expect(call('runs.steer', { runId: id, text: 'Too late.' })).rejects.toMatchObject({ code: 'run_not_active' })
+    expect(of(id).some((event) => event.type === 'message.steered')).toBe(false)
+  })
 })

package/src/sessions/policy.ts

@@ -17,6 +17,10 @@ export interface ScopeDecision {
   allowed: boolean
   /** Not allowed as it stands, but a person may approve this one call. */
   requiresApproval?: boolean
+  /** Per-tool remembered approvals never answer this call. */
+  humanOnly?: boolean
+  /** Whether the global always-approve switch may answer a human-only call. Defaults to false. */
+  allowGlobalApproval?: boolean
   reason?: string | null
 }
 

package/src/sessions/questionBatches.test.ts

@@ -0,0 +1,110 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, test } from 'vitest'
+
+import { closeIndex } from '../core/index'
+import { runEventPayloadSchemas, runRecordSchema, type RunEvent } from './contracts'
+import { RunRegistry } from './registry'
+import { readEvents, saveRun } from './runStore'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) closeIndex(root)
+})
+
+function fixture() {
+  const root = mkdtempSync(join(tmpdir(), 'harness-question-batch-'))
+  roots.push(root)
+  saveRun(root, runRecordSchema.parse({
+    id: 'run-1',
+    sessionId: 'session-1',
+    projectId: null,
+    mode: 'chat',
+    harness: 'pi',
+    sessionType: 'structured',
+    nativeSessionId: null,
+    workingDirectory: null,
+    worktreeId: null,
+    goal: null,
+    status: 'running',
+    startedAt: 'start',
+    endedAt: null
+  }))
+  const registry = new RunRegistry({ root: () => root })
+  const run = registry.start('session-1', 'run-1')
+  return { root, registry, run }
+}
+
+test('question batches validate all answers before resolving and retain choice notes', async () => {
+  const { root, registry, run } = fixture()
+  expect(() => run.requestAnswers([])).toThrow(/between one and five/)
+  expect(() => run.requestAnswers(Array.from({ length: 6 }, () => ({ question: 'Q', options: [], multiSelect: false, allowText: true })))).toThrow(/between one and five/)
+
+  const result = run.requestAnswers([
+    { summary: 'Project scope', question: 'What should change?', options: [{ label: 'UI' }, { label: 'API' }], multiSelect: true, allowText: true },
+    { summary: 'Target date', question: 'When should it ship?', options: [{ label: 'Soon' }, { label: 'Later' }], multiSelect: false, allowText: false }
+  ])
+  let settled = false
+  void result.then(() => { settled = true })
+
+  const requested = readEvents(root, 'run-1').filter((event) => event.type === 'question.requested')
+  expect(requested).toHaveLength(2)
+  const [first, second] = requested.map((event) => event.payload as { questionId: string; summary: string; batchId: string; batchIndex: number; batchCount: number })
+  expect(first).toMatchObject({ summary: 'Project scope', batchIndex: 1, batchCount: 2 })
+  expect(second).toMatchObject({ summary: 'Target date', batchId: first.batchId, batchIndex: 2, batchCount: 2 })
+  expect(() => registry.answerQuestion('run-1', first.questionId, { selected: ['UI'] })).toThrow(/together/)
+
+  expect(() => registry.answerQuestions('run-1', first.batchId, [
+    { questionId: first.questionId, answer: { selected: ['UI'] } },
+    { questionId: second.questionId, answer: { selected: ['Later'], notes: { Soon: 'wrong choice' } } }
+  ])).toThrow(/selected choices/)
+  await Promise.resolve()
+  expect(settled).toBe(false)
+
+  registry.answerQuestions('run-1', first.batchId, [
+    { questionId: second.questionId, answer: { selected: ['Soon'] } },
+    { questionId: first.questionId, answer: { selected: ['UI'], notes: { UI: 'Keep keyboard navigation.' } } }
+  ])
+  await expect(result).resolves.toEqual([
+    { selected: ['UI'], notes: { UI: 'Keep keyboard navigation.' } },
+    { selected: ['Soon'] }
+  ])
+
+  const answered = readEvents(root, 'run-1').filter((event) => event.type === 'question.answered')
+  expect(answered).toHaveLength(2)
+  expect(answered.find((event) => (event.payload as { questionId: string }).questionId === first.questionId)?.payload).toMatchObject({
+    batchId: first.batchId,
+    batchIndex: 1,
+    batchCount: 2,
+    notes: { UI: 'Keep keyboard navigation.' }
+  })
+})
+
+test('legacy single questions remain valid alongside batch event metadata', () => {
+  const { root, registry, run } = fixture()
+  const answer = run.requestAnswer({ question: 'Continue?', options: [{ label: 'Yes' }], multiSelect: false, allowText: false })
+  const request = readEvents(root, 'run-1').find((event) => event.type === 'question.requested')!
+  expect(runEventPayloadSchemas['question.requested'].safeParse(request.payload).success).toBe(true)
+  expect(runEventPayloadSchemas['question.requested'].safeParse({ ...(request.payload as object), batchId: 'partial' }).success).toBe(false)
+  registry.answerQuestion('run-1', (request.payload as { questionId: string }).questionId, { selected: ['Yes'] })
+  return expect(answer).resolves.toEqual({ selected: ['Yes'] })
+})
+
+test('answer batch method rejects duplicate and foreign question ids without settling the batch', async () => {
+  const { root, registry, run } = fixture()
+  const result = run.requestAnswers([
+    { summary: 'First', question: 'First?', options: [], multiSelect: false, allowText: true },
+    { summary: 'Second', question: 'Second?', options: [], multiSelect: false, allowText: true }
+  ])
+  const requested = readEvents(root, 'run-1').filter((event) => event.type === 'question.requested')
+  const [first, second] = requested.map((event) => event.payload as { questionId: string; batchId: string })
+  const answers = [{ questionId: first.questionId, answer: { selected: [], text: 'a' } }, { questionId: second.questionId, answer: { selected: [], text: 'b' } }]
+  expect(() => registry.answerQuestions('run-1', 'other-batch', answers)).toThrow(/batch/)
+  expect(() => registry.answerQuestions('run-1', first.batchId, [answers[0], answers[0]])).toThrow(/batch/)
+  expect(() => registry.answerQuestions('another-run', first.batchId, answers)).toThrow(/batch/)
+  const events: RunEvent[] = readEvents(root, 'run-1')
+  expect(events.filter((event) => event.type === 'question.answered')).toHaveLength(0)
+  registry.answerQuestions('run-1', first.batchId, answers)
+  await expect(result).resolves.toHaveLength(2)
+})

package/src/sessions/registry.ts

@@ -27,6 +27,7 @@ export interface ApprovalInput {
 export interface QuestionInput {
   requestId?: string
   userOnly?: boolean
+  summary?: string
   question: string
   options: QuestionOption[]
   multiSelect: boolean
@@ -36,6 +37,21 @@ export interface QuestionInput {
 export interface QuestionAnswer {
   selected: string[]
   text?: string
+  /** Optional notes keyed by the selected choice label. */
+  notes?: Record<string, string>
+}
+
+interface QuestionBatchMetadata {
+  batchId: string
+  batchIndex: number
+  batchCount: number
+}
+
+interface PendingQuestion {
+  runId: string
+  input: QuestionInput
+  batch?: QuestionBatchMetadata
+  resolve: (answer: QuestionAnswer) => void
 }
 
 export interface ActiveRun {
@@ -43,10 +59,14 @@ export interface ActiveRun {
   sessionId: string
   emit(type: RunEventType, payload: unknown, native?: unknown): void
   onInterrupt(handler: () => Promise<void> | void): void
+  /** Hands a message to the model after its current step; the session registers how. */
+  onSteer(handler: (text: string) => Promise<void> | void): void
   /** Resolves when the user decides; only the approval with this exact id can be resolved by it. */
   requestApproval(input: ApprovalInput): Promise<ApprovalDecision>
   /** Asks the user a question and resolves with their answer. */
   requestAnswer(input: QuestionInput): Promise<QuestionAnswer>
+  /** Asks one to five related questions and resolves only after the whole batch is answered. */
+  requestAnswers(inputs: QuestionInput[]): Promise<QuestionAnswer[]>
   finish(outcome: 'completed' | 'failed' | 'interrupted', failure?: { code: string; message: string }): void
   readonly finished: boolean
 }
@@ -64,12 +84,12 @@ export interface RegistryOptions {
   redact?: (event: RunEvent) => void
 }
 
-type LiveRun = ActiveRun & { interrupt: () => Promise<void> }
+type LiveRun = ActiveRun & { interrupt: () => Promise<void>; steer: (text: string) => Promise<void> }
 
 export class RunRegistry {
   private readonly runs = new Map<string, LiveRun>()
   private readonly approvals = new Map<string, { runId: string; resolve: (decision: ApprovalDecision) => void }>()
-  private readonly questions = new Map<string, { runId: string; input: QuestionInput; resolve: (answer: QuestionAnswer) => void }>()
+  private readonly questions = new Map<string, PendingQuestion>()
   private readonly nativeCleared = new Map<string, string>()
   private readonly stopping = new Set<string>()
   private readonly listeners: RunListener[] = []
@@ -111,9 +131,32 @@ export class RunRegistry {
     }
     let finished = false
     const interruptHandlers: Array<() => Promise<void> | void> = []
+    let steerHandler: ((text: string) => Promise<void> | void) | null = null
     const waitingStatus = (): string =>
       [...this.approvals.values()].some((request) => request.runId === runId) ? 'waiting_for_approval' : [...this.questions.values()].some((request) => request.runId === runId) ? 'waiting_for_input' : 'running'
 
+    const requestQuestion = (input: QuestionInput, batch?: QuestionBatchMetadata, statusEvent = true): Promise<QuestionAnswer> => {
+      const { requestId, ...payload } = input
+      const questionId = requestId ?? randomUUID()
+      if (finished || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] })
+      if (this.questions.has(questionId)) throw new HarnessError('invalid_request', 'This question id is already pending.')
+      return new Promise<QuestionAnswer>((resolve) => {
+        this.questions.set(questionId, {
+          runId,
+          input,
+          ...(batch ? { batch } : {}),
+          resolve: (answer) => {
+            this.questions.delete(questionId)
+            emit('question.answered', { questionId, ...answer, ...(batch ?? {}) })
+            emit('status.changed', { status: waitingStatus() })
+            resolve(answer)
+          }
+        })
+        emit('question.requested', { questionId, ...payload, ...(batch ?? {}) })
+        if (statusEvent) emit('status.changed', { status: 'waiting_for_input' })
+      })
+    }
+
     const emit = (type: RunEventType, payload: unknown, native?: unknown): void => {
       if (finished) return
       const parsed = runEventSchema.safeParse({ id: randomUUID(), runId, sessionId, sequence, timestamp: new Date().toISOString(), type, payload, ...(native === undefined ? {} : { native }) })
@@ -130,6 +173,13 @@ export class RunRegistry {
       sessionId,
       emit,
       onInterrupt: (handler) => void interruptHandlers.push(handler),
+      onSteer: (handler) => {
+        steerHandler = handler
+      },
+      steer: async (text) => {
+        if (finished || !steerHandler) throw new HarnessError('run_not_active', 'This run is not accepting messages.')
+        await steerHandler(text)
+      },
       requestApproval: async (input) => {
         const { requestId, standing = 'full', timeoutMs, ...payload } = input
         const approvalId = requestId ?? randomUUID()
@@ -160,24 +210,20 @@ export class RunRegistry {
           })
         })
       },
-      requestAnswer: (input) => {
-        const { requestId, ...payload } = input
-        const questionId = requestId ?? randomUUID()
-        if (finished || this.nativeCleared.delete(questionId)) return Promise.resolve({ selected: [] })
-        emit('question.requested', { questionId, ...payload })
+      requestAnswer: (input) => requestQuestion(input),
+      requestAnswers: (inputs) => {
+        if (!Array.isArray(inputs) || inputs.length < 1 || inputs.length > 5) {
+          throw new HarnessError('invalid_request', 'A question batch must contain between one and five questions.')
+        }
+        const requestedIds = inputs.flatMap((input) => input.requestId ? [input.requestId] : [])
+        if (new Set(requestedIds).size !== requestedIds.length || requestedIds.some((id) => this.questions.has(id))) {
+          throw new HarnessError('invalid_request', 'Question ids in a batch must be unique and not already pending.')
+        }
+        if (finished) return Promise.resolve(inputs.map(() => ({ selected: [] })))
+        const batchId = randomUUID()
+        const answers = inputs.map((input, index) => requestQuestion(input, { batchId, batchIndex: index + 1, batchCount: inputs.length }, false))
         emit('status.changed', { status: 'waiting_for_input' })
-        return new Promise<QuestionAnswer>((resolve) => {
-          this.questions.set(questionId, {
-            runId,
-            input,
-            resolve: (answer) => {
-              this.questions.delete(questionId)
-              emit('question.answered', { questionId, ...answer })
-              emit('status.changed', { status: waitingStatus() })
-              resolve(answer)
-            }
-          })
-        })
+        return Promise.all(answers)
       },
       finish: (outcome, failure) => {
         if (finished) return
@@ -243,6 +289,13 @@ export class RunRegistry {
     return null
   }
 
+  /** Hands a message to a live run's model after its current step. Throws `run_not_active` when the run cannot take it. */
+  async steer(runId: string, text: string): Promise<void> {
+    const run = this.runs.get(runId)
+    if (!run) throw new HarnessError('run_not_active', 'This run is not active.')
+    await run.steer(text)
+  }
+
   async interrupt(runId: string): Promise<void> {
     const run = this.runs.get(runId)
     if (!run) throw new HarnessError('run_not_active', 'This run is not active.')
@@ -272,10 +325,44 @@ export class RunRegistry {
   answerQuestion(runId: string, questionId: string, answer: QuestionAnswer): void {
     const question = this.questions.get(questionId)
     if (!question || question.runId !== runId) throw new HarnessError('question_not_pending', 'This question is not waiting for an answer.')
-    if ((!question.input.multiSelect && answer.selected.length > 1) || answer.selected.some((label) => !question.input.options.some((option) => option.label === label)) || (answer.text && !question.input.allowText)) {
-      throw new HarnessError('invalid_answer', 'Choose the offered options or an allowed text answer.')
+    if (question.batch) throw new HarnessError('question_batch_required', 'Answer every question in this batch together.')
+    question.resolve(this.validateAnswer(question.input, answer))
+  }
+
+  answerQuestions(runId: string, batchId: string, answers: Array<{ questionId: string; answer: QuestionAnswer }>): void {
+    const questions = [...this.questions.entries()].filter(([, pending]) => pending.runId === runId && pending.batch?.batchId === batchId)
+    if (!questions.length || answers.length !== questions.length || new Set(answers.map(({ questionId }) => questionId)).size !== answers.length) {
+      throw new HarnessError('question_not_pending', 'This question batch is not waiting for an answer.')
+    }
+    const pendingById = new Map(questions)
+    const validated = answers.map(({ questionId, answer }) => {
+      const pending = pendingById.get(questionId)
+      if (!pending) throw new HarnessError('question_not_pending', 'Every question in the batch must be answered together.')
+      return { pending, answer: this.validateAnswer(pending.input, answer) }
+    })
+    for (const { pending, answer } of validated) pending.resolve(answer)
+  }
+
+  private validateAnswer(input: QuestionInput, answer: QuestionAnswer): QuestionAnswer {
+    const selected = answer.selected
+    const selectedLabels = new Set(selected)
+    const notes: Record<string, string> = {}
+    for (const [label, note] of Object.entries(answer.notes ?? {})) {
+      const normalized = typeof note === 'string' ? note.trim() : ''
+      if (normalized) notes[label] = normalized
+    }
+    const text = answer.text?.trim()
+    if (
+      (!input.multiSelect && selected.length > 1) ||
+      selectedLabels.size !== selected.length ||
+      selected.some((label) => !input.options.some((option) => option.label === label)) ||
+      (text && !input.allowText) ||
+      Object.keys(notes).some((label) => !selectedLabels.has(label)) ||
+      Object.values(notes).some((note) => note.length > 10_000)
+    ) {
+      throw new HarnessError('invalid_answer', 'Choose the offered options or an allowed text answer, and attach notes only to selected choices.')
     }
-    question.resolve(answer)
+    return { selected, ...(text ? { text } : {}), ...(Object.keys(notes).length ? { notes } : {}) }
   }
 
   activeRunIds(): string[] {