@robhowley/pi-structured-return 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Howley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# pi-structured-return
+
+Structured command execution for pi agents: compact results for the model, full logs for humans.
+
+Cross-platform Pi package that combines:
+- a `structured-return` skill for choosing compact / machine-readable command forms
+- a `structured-return` extension that captures output, stores artifacts, applies parsers, and falls back to tail + log path
+
+## Token reduction
+
+Tool output is designed for humans: source diffs, line annotations, timing breakdowns, absolute paths repeated on every line. Useful on a terminal. Expensive in a model context, especially on failure when output is most verbose and the model needs to act fast.
+
+Test runners: 3 tests, 1 passing, 1 assertion failure, 1 unexpected error.
+Linters: 1 unused variable warning in a single file.
+
+| Parser | Raw (tokens) | Structured (tokens) | Reduction | Notes |
+|---|---|---|---|---|
+| `pytest-json-report` | 446 | 59 | **87%** | verbose output with source snippets and summary footer |
+| `vitest-json` | 348 | 75 | **78%** | source diff with inline arrows and ANSI color codes per failure |
+| `rspec-json` | 212 | 55 | **74%** | default output with backtrace |
+| `junit-xml` | 263 | 81 | **69%** | gradle console output with build lifecycle noise |
+| `minitest-text` | 168 | 59 | **65%** | default output with backtrace |
+| `ruff-json` | 107 | 52 | **51%** | source context + help text per error |
+| `eslint-json` | 64 | 59 | **8%** | already compact formatter |
+
+Tokens counted with `cl100k_base` (tiktoken). Linter output is more compact than test runner output to begin with, so the baseline reduction is lower. The numbers above are measured against a single file with a single error — a conservative lower bound. Both ruff and eslint repeat absolute file paths per error in their raw output, so reduction grows as violations spread across more files.
+
+## Built-in parsers
+- `pytest-json-report`
+- `ruff-json` (`ruff check` only — `ruff format` has no json support)
+- `eslint-json`
+- `vitest-json`
+- `rspec-json`
+- `minitest-text` (parses default minitest output — no flags or reporters needed)
+- `junit-xml` (JUnit XML — covers pytest `--junitxml`, Gradle, Maven, Jest with `jest-junit`, Go with `go-junit-report`, and any other tool that emits the JUnit XML schema)
+
+## Agentic loops
+
+The token table above measures a single run. In an agentic loop the cost compounds — every tool result accumulates in context for the life of the task.
+
+This applies to any loop: fixing a failing test suite, implementing a feature end-to-end, working through a migration, performance tuning execution times. The agent runs a command, reads the result, makes a change, runs it again. Each iteration adds another tool result to the window. With a noisy CLI that means paying for the same verbose boilerplate on every pass, and the agent has to hold all of it to reason about what changed.
+
+A parser converts each result to a one- or two-line signal. Over 15 iterations, the difference isn't 80 tokens vs 15 tokens — it's 1,200 tokens vs 225, on a single command, for a single task.
+
+## Project-local extension
+
+Built-in parsers cover common tools. For everything else — internal CLIs, custom test runners, proprietary lint tools — add a `.pi/structured-return.json` to your project root.
+
+**Why:** keeps token costs low for tools the built-ins don't know about, without forking the package.
+
+**Two options:**
+
+### 1. Re-use a built-in parser
+
+Route a project-specific command to an existing parser. Use this when your tool's output already matches a supported format (e.g. a test runner that emits JUnit XML).
+
+```json
+// .pi/structured-return.json
+{
+  "parsers": [
+    {
+      "id": "acme-tests",
+      "match": { "argvIncludes": ["acme", "test"] },
+      "parseAs": "junit-xml"
+    }
+  ]
+}
+```
+
+### 2. Write a custom parser
+
+Point to a local `.ts` file for tools with unique output formats.
+
+```json
+// .pi/structured-return.json
+{
+  "parsers": [
+    {
+      "id": "foo-json",
+      "match": { "argvIncludes": ["foo-cli", "check"] },
+      "module": "parsers/foo-cli.js"
+    }
+  ]
+}
+```
+
+```ts
+// .pi/parsers/foo-cli.ts
+import fs from "node:fs";
+import type { RunContext } from "@robhowley/pi-structured-return/types";
+
+export default {
+  id: "foo-json",
+  async parse(ctx: RunContext) {
+    const data = JSON.parse(fs.readFileSync(ctx.stdoutPath, "utf8"));
+    return {
+      tool: "foo-cli",
+      status: data.ok ? "pass" : "fail",
+      summary: data.ok ? "passed" : `${data.errors.length} errors`,
+      failures: data.errors.map((e, i) => ({ id: e.id ?? `error-${i}`, file: e.file, line: e.line, message: e.message })),
+      logPath: ctx.logPath,
+    };
+  },
+};
+```
+
+The parser receives a `RunContext` (command, argv, cwd, stdout/stderr paths, artifact paths, log path) and returns a `ParsedResult`. Match rules support `argvIncludes` (array of required tokens) or `regex` (tested against the full argv string).
+
+## Slash commands
+- `/sr-parsers` — list all registered parsers (built-in and project-local) with their match rules and targets
+
+## Structured result schema
+
+Every parser returns the same shape. The model always knows where to look.
+
+| Field | Type | Description |
+|---|---|---|
+| `tool` | `string` | Name of the tool that ran (`eslint`, `pytest`, etc.) |
+| `exitCode` | `number` | Raw process exit code |
+| `status` | `pass \| fail \| error` | Normalized outcome |
+| `summary` | `string` | One-line human+model readable result (`3 failed, 12 passed`) |
+| `cwd` | `string` | Working directory — anchor for resolving relative paths in failures |
+| `failures` | `{ id, file?, line?, message?, rule? }[]` | Per-failure details with relative file paths |
+| `artifact` | `string?` | Path to the saved report file, if one was written |
+| `logPath` | `string` | Path to full stdout+stderr log |
+| `rawTail` | `string?` | Last 200 lines of log, included on fallback when no parser matched |
+
+## Design
+
+`structured_return` is a separate tool, not a wrapper around `bash`. Intercepting `bash` to silently rewrite commands would override a primitive the model and platform both rely on. Pi's philosophy is to extend rather than obfuscate: features are built on top of the platform, not hidden inside it. A dedicated tool honors that. It adds to the available surface, keeps `bash` honest, and leaves the choice explicit. The skill guides the model toward it; nothing is hijacked to get there.
+

package/extensions/structured-return/examples/.pi/machine-readable.json

@@ -0,0 +1,18 @@
+{
+  "parsers": [
+    {
+      "id": "acme-junit",
+      "match": {
+        "argvIncludes": ["acme", "test"]
+      },
+      "parseAs": "junit-xml"
+    },
+    {
+      "id": "foo-json",
+      "match": {
+        "argvIncludes": ["foo-cli", "check"]
+      },
+      "module": "parsers/foo-cli.js"
+    }
+  ]
+}

package/extensions/structured-return/examples/.pi/parsers/foo-cli.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import type { RunContext } from "../../../src/types.js";
+
+type FooError = { id?: string; file?: string; line?: number; message?: string };
+type FooResult = { ok: boolean; errors?: FooError[] };
+
+export default {
+  id: "foo-json",
+  async parse(ctx: RunContext) {
+    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8");
+    const data = JSON.parse(stdout) as FooResult;
+    return {
+      tool: "foo-cli",
+      status: data.ok ? "pass" : "fail",
+      summary: data.ok ? "foo-cli passed" : `${data.errors?.length ?? 0} foo-cli errors`,
+      failures: (data.errors ?? []).map((e: FooError, i: number) => ({
+        id: e.id ?? `error-${i + 1}`,
+        file: e.file,
+        line: e.line,
+        message: e.message,
+      })),
+      logPath: ctx.logPath,
+    };
+  },
+};

package/extensions/structured-return/src/.tmp/vitest-report.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<testsuites name="vitest tests" tests="21" failures="0" errors="0" time="0.014556541">
+    <testsuite name="index.test.ts" timestamp="2026-03-16T17:34:52.759Z" hostname="Roberts-MBP" tests="9" failures="0" errors="0" skipped="0" time="0.002309">
+        <testcase classname="index.test.ts" name="stripCdPrefix &gt; strips cd /path &amp;&amp; prefix" time="0.000854833">
+        </testcase>
+        <testcase classname="index.test.ts" name="stripCdPrefix &gt; leaves commands without cd unchanged" time="0.000108208">
+        </testcase>
+        <testcase classname="index.test.ts" name="stripCdPrefix &gt; handles paths with no trailing space variations" time="0.000063708">
+        </testcase>
+        <testcase classname="index.test.ts" name="formatResult &gt; includes cwd when set" time="0.000125458">
+        </testcase>
+        <testcase classname="index.test.ts" name="formatResult &gt; omits cwd line when not set" time="0.000084875">
+        </testcase>
+        <testcase classname="index.test.ts" name="formatResult &gt; renders relative paths in failure lines" time="0.000090792">
+        </testcase>
+        <testcase classname="index.test.ts" name="finalizeResult &gt; status error with exit code 0 flips to pass" time="0.000076667">
+        </testcase>
+        <testcase classname="index.test.ts" name="finalizeResult &gt; status error with non-zero exit code stays error" time="0.000056917">
+        </testcase>
+        <testcase classname="index.test.ts" name="finalizeResult &gt; attaches cwd to result" time="0.000058875">
+        </testcase>
+    </testsuite>
+    <testsuite name="parsers/eslint-json.test.ts" timestamp="2026-03-16T17:34:52.759Z" hostname="Roberts-MBP" tests="3" failures="0" errors="0" skipped="0" time="0.003122">
+        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; multiple errors across multiple files → correct relative paths, correct failure count, status fail" time="0.001832041">
+        </testcase>
+        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; no errors → empty failures, status pass" time="0.000366459">
+        </testcase>
+        <testcase classname="parsers/eslint-json.test.ts" name="eslint-json parser &gt; empty stdout → no crash, status pass" time="0.000289">
+        </testcase>
+    </testsuite>
+    <testsuite name="parsers/pytest-json-report.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="4" failures="0" errors="0" skipped="0" time="0.003528333">
+        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; mix of passed and failed tests → correct counts, status fail" time="0.001658708">
+        </testcase>
+        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; all passing → status pass, summary reflects passed count" time="0.00033575">
+        </testcase>
+        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; failed test with longrepr → first line surfaced as message" time="0.000256959">
+        </testcase>
+        <testcase classname="parsers/pytest-json-report.test.ts" name="pytest-json-report parser &gt; missing artifact file → throws" time="0.000615667">
+        </testcase>
+    </testsuite>
+    <testsuite name="parsers/ruff-json.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="3" failures="0" errors="0" skipped="0" time="0.003317375">
+        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; multiple errors across multiple files → correct relative paths, rule code mapped to rule, status fail" time="0.00188625">
+        </testcase>
+        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; no errors → empty failures, status pass" time="0.000399625">
+        </testcase>
+        <testcase classname="parsers/ruff-json.test.ts" name="ruff-json parser &gt; empty stdout → no crash, status pass" time="0.00028175">
+        </testcase>
+    </testsuite>
+    <testsuite name="parsers/tail-fallback.test.ts" timestamp="2026-03-16T17:34:52.760Z" hostname="Roberts-MBP" tests="2" failures="0" errors="0" skipped="0" time="0.002279833">
+        <testcase classname="parsers/tail-fallback.test.ts" name="tail-fallback parser &gt; any command → status error, summary contains log path" time="0.001251">
+        </testcase>
+        <testcase classname="parsers/tail-fallback.test.ts" name="tail-fallback parser &gt; long stdout → tail is bounded to last 200 lines" time="0.000405417">
+        </testcase>
+    </testsuite>
+</testsuites>

package/extensions/structured-return/src/config/project-config.ts

@@ -0,0 +1,10 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserConfigFile, ParserRegistration } from "../types";
+
+export function loadProjectConfig(cwd: string): ParserRegistration[] {
+  const configPath = path.join(cwd, ".pi", "structured-return.json");
+  if (!fs.existsSync(configPath)) return [];
+  const data = JSON.parse(fs.readFileSync(configPath, "utf8")) as ParserConfigFile;
+  return Array.isArray(data.parsers) ? data.parsers : [];
+}

package/extensions/structured-return/src/config/registry.ts

@@ -0,0 +1,89 @@
+import path from "node:path";
+import type { ParserModule, ParserRegistration } from "../types";
+import pytestJsonReport from "../parsers/pytest-json-report";
+import ruffJson from "../parsers/ruff-json";
+import eslintJson from "../parsers/eslint-json";
+import vitestJson from "../parsers/vitest-json";
+import rspecJson from "../parsers/rspec-json";
+import minitestText from "../parsers/minitest-text";
+import junitXml from "../parsers/junit-xml";
+import tailFallback from "../parsers/tail-fallback";
+
+const builtIns: Record<string, ParserModule> = {
+  "pytest-json-report": pytestJsonReport,
+  "ruff-json": ruffJson,
+  "eslint-json": eslintJson,
+  "vitest-json": vitestJson,
+  "rspec-json": rspecJson,
+  "minitest-text": minitestText,
+  "junit-xml": junitXml,
+  "tail-fallback": tailFallback,
+};
+
+/** Built-in detection patterns — fire when no explicit parseAs or project registration matched. */
+const AUTO_DETECT: Array<{ parserId: string; detect: (argv: string[]) => boolean }> = [
+  {
+    parserId: "eslint-json",
+    detect: (argv) => argv.includes("eslint") && argv.includes("-f") && argv.includes("json"),
+  },
+  {
+    parserId: "ruff-json",
+    detect: (argv) =>
+      argv.includes("ruff") &&
+      argv.some((a) => a === "--output-format=json" || a === "json") &&
+      (argv.includes("--output-format=json") || argv.includes("--output-format")),
+  },
+  {
+    parserId: "pytest-json-report",
+    detect: (argv) => argv.includes("pytest") && argv.includes("--json-report"),
+  },
+  {
+    parserId: "vitest-json",
+    detect: (argv) => argv.includes("vitest") && argv.includes("--reporter=json"),
+  },
+  {
+    parserId: "rspec-json",
+    detect: (argv) =>
+      argv.includes("rspec") &&
+      (argv.includes("--format=json") || (argv.includes("--format") && argv.includes("json"))),
+  },
+  {
+    parserId: "junit-xml",
+    detect: (argv) =>
+      argv.some((a) => a.startsWith("--junitxml") || a.startsWith("--junit-xml") || a === "--format=junit"),
+  },
+];
+
+export async function resolveParser(opts: {
+  cwd: string;
+  parseAs?: string;
+  argv: string[];
+  registrations: ParserRegistration[];
+}): Promise<ParserModule> {
+  if (opts.parseAs && builtIns[opts.parseAs]) return builtIns[opts.parseAs];
+
+  const matched = opts.registrations.find((reg) => matches(reg, opts.argv));
+  if (matched?.parseAs && builtIns[matched.parseAs]) return builtIns[matched.parseAs];
+  if (matched?.module) {
+    const modulePath = path.resolve(opts.cwd, ".pi", matched.module);
+    const loaded = await import(modulePath);
+    return loaded.default ?? loaded;
+  }
+
+  const autoMatched = AUTO_DETECT.find((d) => d.detect(opts.argv));
+  if (autoMatched) return builtIns[autoMatched.parserId];
+
+  return builtIns["tail-fallback"];
+}
+
+function matches(reg: ParserRegistration, argv: string[]): boolean {
+  if (reg.match?.argvIncludes?.length) {
+    const ok = reg.match.argvIncludes.every((token) => argv.includes(token));
+    if (!ok) return false;
+  }
+  if (reg.match?.regex) {
+    const text = argv.join(" ");
+    if (!new RegExp(reg.match.regex).test(text)) return false;
+  }
+  return Boolean(reg.match?.argvIncludes?.length || reg.match?.regex);
+}

package/extensions/structured-return/src/index.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect } from "vitest";
+import { stripCdPrefix, formatResult, finalizeResult } from "./index";
+
+describe("stripCdPrefix", () => {
+  it("strips cd /path && prefix", () => {
+    expect(stripCdPrefix("cd /some/path && npx eslint . -f json")).toBe("npx eslint . -f json");
+  });
+
+  it("leaves commands without cd unchanged", () => {
+    expect(stripCdPrefix("npx eslint . -f json")).toBe("npx eslint . -f json");
+  });
+
+  it("handles paths with no trailing space variations", () => {
+    expect(stripCdPrefix("cd /a/b/c &&npx eslint .")).toBe("npx eslint .");
+  });
+});
+
+describe("formatResult", () => {
+  it("includes cwd when set", () => {
+    const result = formatResult({
+      tool: "eslint",
+      exitCode: 1,
+      status: "fail",
+      summary: "1 lint errors",
+      cwd: "/project",
+      failures: [],
+    });
+    expect(result).toContain("cwd: /project");
+  });
+
+  it("omits cwd line when not set", () => {
+    const result = formatResult({
+      tool: "eslint",
+      exitCode: 0,
+      status: "pass",
+      summary: "no lint errors",
+    });
+    expect(result).not.toContain("cwd:");
+  });
+
+  it("renders relative paths in failure lines", () => {
+    const result = formatResult({
+      tool: "eslint",
+      exitCode: 1,
+      status: "fail",
+      summary: "1 lint errors",
+      cwd: "/project",
+      failures: [
+        { id: "src/foo.ts:10:rule", file: "src/foo.ts", line: 10, message: "Unexpected any.", rule: "no-explicit-any" },
+      ],
+    });
+    expect(result).toContain("src/foo.ts:10");
+    expect(result).not.toContain("/project/src/foo.ts");
+  });
+});
+
+describe("finalizeResult", () => {
+  it("status error with exit code 0 flips to pass", () => {
+    const result = finalizeResult(
+      {
+        tool: "unknown",
+        status: "error",
+        summary: "no parser matched; returning tail + log path",
+        logPath: "/log",
+      },
+      0,
+      "/log",
+      "/project"
+    );
+    expect(result.status).toBe("pass");
+    expect(result.summary).toBe("command completed; no parser matched");
+  });
+
+  it("status error with non-zero exit code stays error", () => {
+    const result = finalizeResult(
+      {
+        tool: "unknown",
+        status: "error",
+        summary: "no parser matched; returning tail + log path",
+        logPath: "/log",
+      },
+      1,
+      "/log",
+      "/project"
+    );
+    expect(result.status).toBe("error");
+  });
+
+  it("attaches cwd to result", () => {
+    const result = finalizeResult(
+      { tool: "eslint", status: "pass", summary: "no lint errors", logPath: "/log" },
+      0,
+      "/log",
+      "/project"
+    );
+    expect(result.cwd).toBe("/project");
+  });
+});

package/extensions/structured-return/src/index.ts

@@ -0,0 +1,161 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import type { ObservedRunArgs, ParsedResult, RunContext } from "./types";
+import { ensureRunDir, writeRunArtifacts } from "./storage/log-store";
+import { loadProjectConfig } from "./config/project-config";
+import { resolveParser } from "./config/registry";
+
+const BUILT_IN_PARSER_IDS = ["pytest-json-report", "ruff-json", "eslint-json", "vitest-json", "tail-fallback"];
+
+export default function structuredReturn(pi: ExtensionAPI) {
+  pi.registerCommand("sr-parsers", {
+    description: "List all structured-return parsers: built-ins and project-local registrations",
+    handler: async (_args, ctx) => {
+      const lines: string[] = ["structured-return parsers", ""];
+
+      lines.push("built-in:");
+      for (const id of BUILT_IN_PARSER_IDS) {
+        lines.push(`  ${id}`);
+      }
+
+      const projectRegistrations = loadProjectConfig(ctx.cwd);
+      lines.push("");
+      lines.push("project-local (.pi/structured-return.json):");
+      if (projectRegistrations.length === 0) {
+        lines.push("  (none)");
+      } else {
+        for (const reg of projectRegistrations) {
+          const via = reg.parseAs ? `→ ${reg.parseAs}` : reg.module ? `→ module: ${reg.module}` : "";
+          const match = reg.match?.argvIncludes
+            ? `argv includes [${reg.match.argvIncludes.join(", ")}]`
+            : reg.match?.regex
+              ? `regex: ${reg.match.regex}`
+              : "(no match rule)";
+          lines.push(`  ${reg.id}  ${match}  ${via}`);
+        }
+      }
+
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  pi.on("before_agent_start", async (event) => {
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        "\n\nWhen running lint, test, build, or other shell commands, load and follow the `structured-return` skill before choosing how to invoke them.",
+    };
+  });
+
+  pi.registerTool({
+    name: "structured_return",
+    label: "Structured Return",
+    description:
+      "Run a command, store full logs, apply an explicit or registered parser when available, and fall back to tail + log path.",
+    parameters: Type.Object({
+      command: Type.String(),
+      cwd: Type.Optional(Type.String()),
+      parseAs: Type.Optional(Type.String()),
+      artifactPaths: Type.Optional(Type.Array(Type.String())),
+    }),
+    async execute(
+      _toolCallId: string,
+      args: ObservedRunArgs,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      ctx: ExtensionContext
+    ) {
+      const cwd = args.cwd ?? ctx.cwd ?? process.cwd();
+      const runDir = ensureRunDir(cwd);
+      const runId = randomUUID();
+      const argv = shellSplit(args.command);
+      const { stdout, stderr, exitCode } = await runCommand(args.command, cwd);
+      const logs = writeRunArtifacts(runDir, runId, stdout, stderr);
+      const artifactPaths = (args.artifactPaths ?? []).map((p) => (path.isAbsolute(p) ? p : path.join(cwd, p)));
+      const runCtx: RunContext = {
+        command: args.command,
+        argv,
+        cwd,
+        artifactPaths,
+        ...logs,
+      };
+      const registrations = loadProjectConfig(cwd);
+      const parser = await resolveParser({ cwd, parseAs: args.parseAs, argv, registrations });
+      const parsed = await parser.parse(runCtx);
+      const result = finalizeResult(parsed, exitCode, logs.logPath, cwd);
+
+      return {
+        content: [{ type: "text" as const, text: `${stripCdPrefix(args.command)} → ${formatResult(result)}` }],
+        details: { exitCode, logPath: logs.logPath, parser: parser.id },
+      };
+    },
+    renderCall(args: ObservedRunArgs) {
+      return new Text(`structured_return ${args.command}`, 0, 0);
+    },
+    renderResult(result: { content?: Array<{ type: string; text?: string }> }) {
+      const text = result?.content?.[0]?.text ?? "structured_return complete";
+      return new Text(text, 0, 0);
+    },
+  });
+}
+
+export function formatResult(result: ParsedResult): string {
+  const lines: string[] = [];
+  if (result.cwd) lines.push(`cwd: ${result.cwd}`);
+  lines.push(result.summary);
+  for (const f of result.failures ?? []) {
+    const location = [f.file, f.line].filter(Boolean).join(":");
+    const rule = f.rule ? `  [${f.rule}]` : "";
+    lines.push(`  ${location}  ${f.message ?? ""}${rule}`);
+  }
+  return lines.join("\n");
+}
+
+export function stripCdPrefix(command: string): string {
+  return command.replace(/^cd\s+\S+\s*&&\s*/, "");
+}
+
+function shellSplit(command: string): string[] {
+  return command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g)?.map((s) => s.replace(/^['"]|['"]$/g, "")) ?? [];
+}
+
+function runCommand(command: string, cwd: string): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve) => {
+    const proc = spawn(command, { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    proc.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    proc.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1 }));
+  });
+}
+
+export function finalizeResult(
+  result: Omit<ParsedResult, "exitCode">,
+  exitCode: number,
+  logPath: string,
+  cwd: string
+): ParsedResult {
+  if (result.status === "error" && exitCode === 0) {
+    return {
+      ...result,
+      exitCode,
+      cwd,
+      status: "pass",
+      summary:
+        result.summary === "no parser matched; returning tail + log path"
+          ? "command completed; no parser matched"
+          : result.summary,
+      logPath,
+    };
+  }
+  return { ...result, exitCode, cwd, logPath };
+}

package/extensions/structured-return/src/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"4.1.0","results":[[":parsers/pytest-json-report.test.ts",{"duration":8.454000000000008,"failed":false}],[":parsers/ruff-json.test.ts",{"duration":2.925207999999998,"failed":false}],[":index.test.ts",{"duration":2.2829590000000053,"failed":false}],[":parsers/eslint-json.test.ts",{"duration":3.558458999999999,"failed":false}],[":parsers/tail-fallback.test.ts",{"duration":3.911292000000003,"failed":false}],[":parsers/vitest-json.test.ts",{"duration":7.248625000000004,"failed":false}],[":parsers/rspec-json.test.ts",{"duration":7.745584000000008,"failed":false}],[":parsers/junit-xml.test.ts",{"duration":6.386042000000003,"failed":false}],[":parsers/minitest-text.test.ts",{"duration":6.155249999999995,"failed":false}]]}