read_agent_output

Extract structured content from agent terminals using delimiter markers like OUTPUT_START/OUTPUT_END to retrieve specific output sections for processing.

Instructions

Extract structured output from an agent's terminal between delimiter markers (e.g., REVIEW_OUTPUT_START / REVIEW_OUTPUT_END). Returns the content between the markers, or null if not found.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`surface`	Yes	Target surface ref (e.g., 'surface:78')
`tag`	No	Delimiter tag name. Looks for {TAG}_START and {TAG}_END markers. Default: OUTPUT (matches OUTPUT_START/OUTPUT_END). Examples: REVIEW_OUTPUT, SYNTHESIS_OUTPUT, PUSHBACK_OUTPUT	OUTPUT
`lines`	No	Number of screen lines to scan (default: 200)
`workspace`	No	Target workspace ref

Implementation Reference

src/server.ts:906-948 (handler)

The handler function that reads the terminal screen and extracts content between the specified markers.

async (args) => {
  try {
    const opts: Record<string, unknown> = {
      lines: args.lines,
      scrollback: true,
    };
    if (args.workspace) opts.workspace = args.workspace;

    const raw = await client.readScreen(args.surface, opts);
    const text =
      typeof raw === "string"
        ? raw
        : ((raw as { content?: string }).content ?? "");

    const startMarker = `${args.tag}_START`;
    const endMarker = `${args.tag}_END`;

    const startIdx = text.indexOf(startMarker);
    const endIdx = text.indexOf(endMarker);

    if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
      return ok({
        found: false,
        tag: args.tag,
        surface: args.surface,
        content: null,
      });
    }

    const content = text
      .slice(startIdx + startMarker.length, endIdx)
      .trim();

    return ok({
      found: true,
      tag: args.tag,
      surface: args.surface,
      content,
    });
  } catch (e) {
    return err(e);
  }
},

src/server.ts:890-905 (schema)

Input validation schema for the read_agent_output tool.

{
  surface: z.string().describe("Target surface ref (e.g., 'surface:78')"),
  tag: z
    .string()
    .optional()
    .default("OUTPUT")
    .describe(
      "Delimiter tag name. Looks for {TAG}_START and {TAG}_END markers. Default: OUTPUT (matches OUTPUT_START/OUTPUT_END). Examples: REVIEW_OUTPUT, SYNTHESIS_OUTPUT, PUSHBACK_OUTPUT",
    ),
  lines: z
    .number()
    .optional()
    .default(200)
    .describe("Number of screen lines to scan (default: 200)"),
  workspace: z.string().optional().describe("Target workspace ref"),
},

src/server.ts:887-905 (registration)

Tool registration for read_agent_output.

server.tool(
  "read_agent_output",
  "Extract structured output from an agent's terminal between delimiter markers (e.g., REVIEW_OUTPUT_START / REVIEW_OUTPUT_END). Returns the content between the markers, or null if not found.",
  {
    surface: z.string().describe("Target surface ref (e.g., 'surface:78')"),
    tag: z
      .string()
      .optional()
      .default("OUTPUT")
      .describe(
        "Delimiter tag name. Looks for {TAG}_START and {TAG}_END markers. Default: OUTPUT (matches OUTPUT_START/OUTPUT_END). Examples: REVIEW_OUTPUT, SYNTHESIS_OUTPUT, PUSHBACK_OUTPUT",
      ),
    lines: z
      .number()
      .optional()
      .default(200)
      .describe("Number of screen lines to scan (default: 200)"),
    workspace: z.string().optional().describe("Target workspace ref"),
  },

cmuxlayer