feat(agent): add result_schema, and anchor the fullscreen transcript

.changeset/fullscreen-dock-anchor.md

@@ -0,0 +1,5 @@
+---
+"echadron": patch
+---
+
+Fix the fullscreen layout stranding a short conversation at the top of the screen. The transcript now sits against the input box, with empty space above it rather than a gap in the middle, and a squeezed terminal gives up transcript rows instead of dropping the activity and todo lines.

.changeset/subagent-result-schema.md

@@ -0,0 +1,5 @@
+---
+"echadron": minor
+---
+
+`Agent` and `AgentSwarm` accept a `result_schema`: a flat JSON Schema the subagent must satisfy by ending its final message with a matching JSON object. The parent then receives parsed objects it can merge — a swarm report of JSON instead of a pile of prose — while a child that fails to comply keeps its prose plus a marker, so nothing is lost.

apps/kimi-code/src/tui/tui-state.ts

@@ -29,6 +29,9 @@ import {
   type TUIStartupState,
 } from './types';
 
+/** Keeps height deficit on the transcript; see the root-stack comment. */
+const DOCK_SHRINK_WEIGHT = 0.001;
+
 export interface TUIState {
   ui: TUI;
   terminal: ProcessTerminal;
@@ -125,8 +128,22 @@ export function createTUIState(options: KimiTUIOptions): TUIState {
     dockContainer.addChild(btwPanelContainer, { shrink: 1, minSize: 0 });
     dockContainer.addChild(editorContainer, { shrink: 1, minSize: 3 });
     const root = new VStack();
-    root.addChild(scrollView, { basis: 0, grow: 1, shrink: 1, minSize: 1 });
-    root.addChild(dockContainer, { basis: 'auto', grow: 0, shrink: 1, minSize: 1 });
+    // The spacer bottom-anchors an underfilled transcript: on a short session
+    // the conversation sits just above the editor instead of stranding at the
+    // top of the screen with a dead void between it and the dock. Once the
+    // transcript outgrows the viewport the spacer collapses to zero and the
+    // ScrollView absorbs the whole height deficit — its shrink weight dwarfs
+    // the dock's, so shrink pressure can never crush the activity and todo
+    // rows the way an evenly weighted stack would.
+    const spacer = new Container();
+    root.addChild(spacer, { basis: 0, grow: 1, shrink: 1, minSize: 0 });
+    root.addChild(scrollView, { basis: 'auto', grow: 0, shrink: 1, minSize: 1 });
+    root.addChild(dockContainer, {
+      basis: 'auto',
+      grow: 0,
+      shrink: DOCK_SHRINK_WEIGHT,
+      minSize: 1,
+    });
     ui.setLayoutRoot(root);
   }
 

apps/kimi-code/test/tui/fullscreen-layout.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Fullscreen (alternate screen) dock layout.
+ *
+ * The root stack is built in `tui-state.ts`. These assertions pin the two
+ * behaviours that are easy to break and invisible to a typecheck: an
+ * underfilled transcript must sit against the dock rather than stranding at
+ * the top of the screen, and shrink pressure must land on the transcript
+ * rather than crushing the activity and todo rows.
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { Container, ScrollView, Text, VStack } from '@moonshot-ai/pi-tui';
+import { TuiAltScreen } from '@moonshot-ai/pi-tui';
+
+import { VirtualTerminal } from '../../../../packages/pi-tui/test/virtual-terminal';
+
+/** Mirrors the root stack `createTuiState` builds for the alternate screen. */
+function buildAltScreen(options: {
+  readonly columns: number;
+  readonly rows: number;
+  readonly transcriptLines: number;
+}): { terminal: VirtualTerminal; tui: TuiAltScreen } {
+  const terminal = new VirtualTerminal(options.columns, options.rows);
+  const tui = new TuiAltScreen(terminal);
+
+  const transcript = new Container();
+  for (let i = 1; i <= options.transcriptLines; i += 1) {
+    transcript.addChild(new Text(`transcript ${String(i)}`, 0, 0));
+  }
+  const scrollView = new ScrollView(transcript, {
+    follow: 'end',
+    primary: true,
+    overscroll: 'chain',
+    scrollbar: 'auto',
+  });
+
+  const activity = new Container();
+  activity.addChild(new Text('ACTIVITY', 0, 0));
+  const todo = new Container();
+  todo.addChild(new Text('TODO', 0, 0));
+  const editor = new Container();
+  editor.addChild(new Text('EDITOR-TOP', 0, 0));
+  editor.addChild(new Text('EDITOR-INPUT', 0, 0));
+  editor.addChild(new Text('EDITOR-BOTTOM', 0, 0));
+  const footer = new Container();
+  footer.addChild(new Text('FOOTER', 0, 0));
+
+  const dock = new VStack();
+  dock.addChild(activity, { shrink: 1, minSize: 0 });
+  dock.addChild(todo, { shrink: 1, minSize: 0 });
+  dock.addChild(editor, { shrink: 1, minSize: 3 });
+  dock.addChild(footer, { shrink: 1, minSize: 1 });
+
+  const root = new VStack();
+  const spacer = new Container();
+  root.addChild(spacer, { basis: 0, grow: 1, shrink: 1, minSize: 0 });
+  root.addChild(scrollView, { basis: 'auto', grow: 0, shrink: 1, minSize: 1 });
+  root.addChild(dock, { basis: 'auto', grow: 0, shrink: 0.001, minSize: 1 });
+  tui.setLayoutRoot(root);
+  return { terminal, tui };
+}
+
+async function viewport(options: {
+  readonly columns: number;
+  readonly rows: number;
+  readonly transcriptLines: number;
+}): Promise<string[]> {
+  const { terminal, tui } = buildAltScreen(options);
+  tui.start();
+  try {
+    await terminal.waitForRender();
+    return terminal.getViewport().map((line: string) => line.trimEnd());
+  } finally {
+    tui.stop();
+  }
+}
+
+describe('fullscreen dock layout', () => {
+  it('anchors a short transcript to the dock instead of the top of the screen', async () => {
+    const lines = await viewport({ columns: 80, rows: 24, transcriptLines: 3 });
+
+    // The regression this guards: without the growable spacer the transcript
+    // sits at row 0 and leaves a dead void between it and the editor, so a
+    // fresh session reads as a gap with text stranded above it.
+    const firstTranscript = lines.findIndex((line) => line.includes('transcript 1'));
+    const editorRow = lines.findIndex((line) => line.includes('EDITOR-INPUT'));
+    expect(firstTranscript).toBeGreaterThan(0);
+    expect(editorRow - firstTranscript).toBeLessThanOrEqual(8);
+    for (const line of lines.slice(0, firstTranscript)) expect(line).toBe('');
+  });
+
+  it('fills the viewport and keeps follow-end when the transcript is long', async () => {
+    const lines = await viewport({ columns: 80, rows: 24, transcriptLines: 60 });
+
+    expect(lines[0]).toContain('transcript');
+    // follow-end: the newest line is on screen, the oldest is scrolled away.
+    expect(lines.some((line) => line.includes('transcript 60'))).toBe(true);
+    expect(lines.some((line) => line.includes('transcript 1 '))).toBe(false);
+  });
+
+  it('spends height deficit on the transcript, never on the dock rows', async () => {
+    // A naive evenly-weighted stack drops ACTIVITY and TODO first, which is
+    // exactly the information a squeezed terminal most needs to keep.
+    for (const rows of [24, 12, 8]) {
+      const lines = await viewport({ columns: 80, rows, transcriptLines: 60 });
+      const joined = lines.join('\n');
+      expect(joined, `rows=${String(rows)}`).toContain('ACTIVITY');
+      expect(joined, `rows=${String(rows)}`).toContain('TODO');
+      expect(joined, `rows=${String(rows)}`).toContain('EDITOR-INPUT');
+      expect(joined, `rows=${String(rows)}`).toContain('FOOTER');
+    }
+  });
+
+  it('keeps the dock intact on a narrow terminal', async () => {
+    const lines = await viewport({ columns: 34, rows: 12, transcriptLines: 20 });
+    const joined = lines.join('\n');
+    expect(joined).toContain('EDITOR-INPUT');
+    expect(joined).toContain('FOOTER');
+  });
+});

packages/agent-core-v2/src/agent/tools/agent-swarm/agent-swarm.ts

@@ -53,6 +53,12 @@ export const AgentSwarmToolInputSchema = z
       .describe(
         'Map of existing subagent agent_id to the prompt used to resume that subagent. These resumed subagents are launched before new item-based subagents.',
       ),
+    result_schema: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe(
+        'Optional JSON Schema (type "object") every subagent must satisfy by ending its final message with a matching JSON object. The aggregated report then carries each subagent\'s parsed object instead of prose, so you can merge findings across the swarm. Keep it flat — a few required string/number/array fields.',
+      ),
     model: z
       .string()
       .trim()

packages/agent-core-v2/src/agent/tools/agent-swarm/agentSwarmTool.ts

@@ -33,6 +33,10 @@ import { toInputJsonSchema } from '#/tool/input-schema';
 import { IConfigService } from '#/app/config/config';
 import { IFlagService } from '#/app/flag/flag';
 import { IModelCatalog } from '#/kosong/model/catalog';
+import {
+  buildResultSchemaInstruction,
+  extractStructuredResult,
+} from '#/agent/tools/agent/resultSchema';
 import { ISessionSwarmService, type SessionSwarmTask } from '#/session/swarm/sessionSwarm';
 import { ISessionAgentProfileCatalog } from '#/session/sessionAgentProfileCatalog/sessionAgentProfileCatalog';
 import { IAgentProfileService } from '#/agent/profile/profile';
@@ -212,7 +216,10 @@ export class AgentSwarmTool implements IAgentSwarmTool {
         data: spec,
         profileName: spec.kind === 'resume' ? 'subagent' : profileName,
         parentToolCallId: toolCallId,
-        prompt: spec.prompt,
+        prompt:
+          args.result_schema === undefined
+            ? spec.prompt
+            : spec.prompt + buildResultSchemaInstruction(args.result_schema),
         description: childDescription(args.description, spec.index, descriptionName),
         swarmIndex: spec.index,
         runInBackground: false,
@@ -245,6 +252,7 @@ export class AgentSwarmTool implements IAgentSwarmTool {
     });
     return renderSwarmResults(
       results.map(({ task, ...result }) => ({ spec: task.data as AgentSwarmSpec, ...result })),
+      args.result_schema,
     );
   }
 }
@@ -320,7 +328,10 @@ function childDescription(swarmDescription: string, index: number, profileName:
   return `${swarmDescription} #${String(index)} (${profileName})`;
 }
 
-function renderSwarmResults(results: readonly SwarmRunResult[]): string {
+function renderSwarmResults(
+  results: readonly SwarmRunResult[],
+  resultSchema?: Record<string, unknown>,
+): string {
   const completed = results.filter((result) => result.status === 'completed').length;
   const failed = results.filter((result) => result.status === 'failed').length;
   const aborted = results.filter((result) => result.status === 'aborted').length;
@@ -343,7 +354,10 @@ function renderSwarmResults(results: readonly SwarmRunResult[]): string {
     const mode = result.spec.kind === 'resume' ? ' mode="resume"' : '';
     const item = result.spec.item === undefined ? '' : ` item="${escapeXmlAttribute(result.spec.item)}"`;
     const state = result.state === undefined ? '' : ` state="${result.state}"`;
-    const body = result.status === 'completed' ? (result.result ?? '') : (result.error ?? 'unknown error');
+    const body =
+      result.status === 'completed'
+        ? renderSwarmBody(result.result ?? '', resultSchema)
+        : (result.error ?? 'unknown error');
     lines.push(
       `<subagent${mode}${agentId}${item}${state} outcome="${result.status}">${body}</subagent>`,
     );
@@ -353,6 +367,20 @@ function renderSwarmResults(results: readonly SwarmRunResult[]): string {
   return lines.join('\n');
 }
 
+/**
+ * Body of one completed subagent. With a `result_schema`, a valid object
+ * replaces the prose entirely — a 100-agent report of JSON objects is
+ * mergeable, one of paragraphs is not. A child that failed to produce the
+ * object keeps its prose plus a marker, so nothing it found is lost.
+ */
+function renderSwarmBody(result: string, schema: Record<string, unknown> | undefined): string {
+  if (schema === undefined) return result;
+  const extracted = extractStructuredResult(result, schema);
+  return extracted.ok
+    ? JSON.stringify(extracted.value)
+    : `${result}\n[structured_result_missing] ${extracted.reason}`;
+}
+
 function normalizeOptionalString(value: string | undefined): string | undefined {
   if (value === undefined) return undefined;
   const trimmed = value.trim();

packages/agent-core-v2/src/agent/tools/agent/agent.ts

@@ -56,6 +56,12 @@ export const SubagentToolInputSchema = z.preprocess(
       .describe(
         'If true, return immediately without waiting for completion. Prefer false unless the task can run independently and there is a clear benefit to not waiting.',
       ),
+    result_schema: z
+      .record(z.string(), z.unknown())
+      .optional()
+      .describe(
+        'Optional JSON Schema (type "object") the subagent must satisfy by ending its final message with a matching JSON object. Use it when you will combine results from several subagents: the tool output then carries the parsed object in a [structured_result] section instead of leaving you to re-read prose. Keep it flat — a few required string/number/array fields.',
+      ),
     model: z
       .string()
       .trim()

packages/agent-core-v2/src/agent/tools/agent/agentTool.ts

@@ -81,6 +81,7 @@ import { ISessionMetadata } from '#/session/sessionMetadata/sessionMetadata';
 import { ISessionWorkspaceContext } from '#/session/workspaceContext/workspaceContext';
 
 import { emitAgentRunSpawned, mirrorAgentRun } from '#/session/subagent/mirrorAgentRun';
+import { buildResultSchemaInstruction, extractStructuredResult } from './resultSchema';
 import { ISessionSubagentService } from '#/session/subagent/subagent';
 import {
   buildSubagentModelDescriptions,
@@ -352,6 +353,10 @@ export class SubagentTool implements ISubagentTool {
       });
     }
 
+    if (args.result_schema !== undefined) {
+      promptText += buildResultSchemaInstruction(args.result_schema);
+    }
+
     const runInBackground = args.run_in_background === true;
     emitAgentRunSpawned(requester, agentId, {
       profileName,
@@ -491,7 +496,7 @@ export class SubagentTool implements ISubagentTool {
           output: formatBackgroundAgentResult(taskId, handle, args.description, allowBackground),
         };
       }
-      return await this.formatForegroundResult(taskId, handle, timeoutMs);
+      return await this.formatForegroundResult(taskId, handle, timeoutMs, args.result_schema);
     } catch (error) {
       return { output: `subagent error: ${launchErrorMessage(error, signal)}`, isError: true };
     }
@@ -501,11 +506,13 @@ export class SubagentTool implements ISubagentTool {
     taskId: string,
     handle: SubagentHandle,
     timeoutMs: number,
+    resultSchema?: Record<string, unknown>,
   ): Promise<ExecutableToolResult> {
     const info = this.tasks.getTask(taskId);
     if (info?.status === 'completed') {
+      const result = await this.tasks.readOutput(taskId);
       return {
-        output: formatForegroundAgentSuccess(handle, await this.tasks.readOutput(taskId)),
+        output: formatForegroundAgentSuccess(handle, result, structuredResultSection(result, resultSchema)),
       };
     }
     const timedOut = info?.status === 'timed_out';
@@ -595,15 +602,40 @@ function formatBackgroundAgentResult(
   ].join('\n');
 }
 
-function formatForegroundAgentSuccess(handle: SubagentHandle, result: string): string {
-  return [
+function formatForegroundAgentSuccess(
+  handle: SubagentHandle,
+  result: string,
+  structuredSection?: string,
+): string {
+  const lines = [
     `agent_id: ${handle.agentId}`,
     `actual_subagent_type: ${handle.profileName}`,
     'status: completed',
     '',
     '[summary]',
     result,
-  ].join('\n');
+  ];
+  if (structuredSection !== undefined) lines.push('', structuredSection);
+  return lines.join('\n');
+}
+
+/**
+ * `[structured_result]` section for the parent to parse, present only when a
+ * `result_schema` was requested. Extraction failure is reported inline rather
+ * than as a tool error: the child did complete, and the parent can resume it
+ * to ask for the object without losing the prose it already produced.
+ */
+function structuredResultSection(
+  result: string,
+  schema: Record<string, unknown> | undefined,
+): string | undefined {
+  if (schema === undefined) return undefined;
+  const extracted = extractStructuredResult(result, schema);
+  if (extracted.ok) return `[structured_result]\n${JSON.stringify(extracted.value)}`;
+  return (
+    `[structured_result_missing]\n${extracted.reason}. ` +
+    'Resume this agent and ask it to reply with only the JSON object.'
+  );
 }
 
 function formatForegroundAgentFailure(