@cosyte/cli 0.0.5 → 0.1.0

package/dist/bin/cosyte-mcp.mjs

@@ -4,28 +4,33 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { parseArgs } from 'util';
 
-// src/core/version.ts
-var VERSION = "0.0.5";
-
 // src/core/exit-codes.ts
 var EXIT = {
   /** Success: the operation completed; `validate` found the input **valid**. */
   OK: 0,
-  /** Operation-level failure: `validate` found the input **invalid** (parseable but non-conformant):
-   * a real, expected CI signal that the message is bad and the tool worked. Never emitted for
-   * unparseable input (that is `DATAERR`). */
+  /** Operation-level failure: `validate` found the input **invalid** (parseable but non-conformant),
+   * or `redact` could not de-identify every locus: a real, expected CI signal that the tool worked
+   * and the operation did not complete. Never emitted for unparseable input (that is `DATAERR`). */
   INVALID: 1,
-  /** Usage error: unknown command, bad flag, missing argument (`EX_USAGE`). */
+  /** Usage error: unknown command, bad flag, missing argument. A value specific to this CLI, not a
+   * `sysexits.h` constant. */
   USAGE: 2,
   /** Data error: input could not be parsed or its format could not be detected (`EX_DATAERR`). */
   DATAERR: 65,
   /** No input: the named file does not exist or is unreadable (`EX_NOINPUT`). */
   NOINPUT: 66,
-  /** Unavailable: a required capability is not yet wired (e.g. `redact` before `@cosyte/deid`), a
-   * distinct non-zero signal that is never a fake success (`EX_UNAVAILABLE`). */
+  /** Unavailable: a required capability is not wired for this input (e.g. `redact` on a format
+   * `@cosyte/deid` has no adapter for, or with that optional library absent), a distinct non-zero
+   * signal that is never a fake success (`EX_UNAVAILABLE`). */
   UNAVAILABLE: 69,
   /** Internal error: an unexpected exception (a bug), distinct from a handled bad input (`EX_SOFTWARE`). */
-  SOFTWARE: 70
+  SOFTWARE: 70,
+  /** Output error: the stream the CLI was writing to closed before the output had been delivered, so
+   * the consumer holds nothing or holds only part of the answer. The shape a downstream consumer
+   * that exits early produces (a pager quit, a `head` that has seen enough). A handled condition the
+   * consumer owns, never a defect in the CLI, so it is deliberately distinct from `SOFTWARE`
+   * (`EX_IOERR`). */
+  IOERR: 74
 };
 
 // src/core/diagnostics.ts
@@ -49,9 +54,27 @@ var CLI_CODES = {
   CLI_PARSER_UNAVAILABLE: "CLI_PARSER_UNAVAILABLE",
   /** The wrapped parser rejected the input. Positional context only, never the offending bytes. Exit `65`. */
   CLI_PARSE_FAILED: "CLI_PARSE_FAILED",
-  /** A command whose ground-layer library is not yet wired (e.g. `redact` before `@cosyte/deid` is
-   * wired). Never a fake success: a distinct, value-free "unavailable" signal. Exit `69`. */
+  /** The input is larger than the documented size limit the CLI reads in one invocation. Raised
+   * against the running byte count while the input is read, so the refusal always arrives before an
+   * allocation ceiling could. Names the limit, never the input. Exit `65`, never `70`. */
+  CLI_INPUT_TOO_LARGE: "CLI_INPUT_TOO_LARGE",
+  /** The output stream could not be written: a consumer that closes the pipe ends the invocation
+   * here rather than as an unhandled platform error, whether it went away part way through a record
+   * stream or before a single-result write was delivered. Names no input, and never the platform's
+   * own error text. Exit `74`. */
+  CLI_OUTPUT_WRITE_FAILED: "CLI_OUTPUT_WRITE_FAILED",
+  /** The BYO ConceptMap supplied to `map-codes` is not valid JSON or not a loadable FHIR ConceptMap.
+   * Names the stable terminology-loader code, never the map's bytes. Exit `65`. */
+  CLI_MAP_INVALID: "CLI_MAP_INVALID",
+  /** A command whose ground-layer library does not cover the resolved format (e.g. `redact` on a
+   * format `@cosyte/deid` ships no adapter for). Never a fake success: a distinct, value-free
+   * "unavailable" signal. Exit `69`. */
   CLI_NOT_IMPLEMENTED: "CLI_NOT_IMPLEMENTED",
+  /** The delegated de-identifier reported that it could not handle every element of the input (a
+   * fail-closed `blocked` locus, or its own fatal). The run is **not** a de-identified copy, so no
+   * output is emitted: an operation-level failure, never a bug. Names loci and codes, never a
+   * value. Exit `1`. */
+  CLI_DEID_INCOMPLETE: "CLI_DEID_INCOMPLETE",
   /** An unexpected internal error (a bug). Exit `70`. */
   CLI_INTERNAL: "CLI_INTERNAL"
 };
@@ -88,8 +111,12 @@ function toCliError(err) {
   );
 }
 
+// src/core/version.ts
+var VERSION = "0.1.0";
+
 // src/core/format.ts
-var SNIFF_BYTES = 512;
+var DETECT_PREFIX_BYTES = 512;
+var SNIFF_BYTES = DETECT_PREFIX_BYTES;
 function leadingText(bytes) {
   const slice = bytes.subarray(0, SNIFF_BYTES);
   let text = new TextDecoder("utf-8", { fatal: false }).decode(slice);
@@ -186,6 +213,21 @@ function asCosyteFormat(value) {
   return KNOWN_FORMATS.includes(value) ? value : null;
 }
 
+// src/core/limits.ts
+var BYTES_PER_MIB = 1024 * 1024;
+var MAX_INPUT_BYTES = 64 * BYTES_PER_MIB;
+function describeByteLimit(limit = MAX_INPUT_BYTES) {
+  const mib = limit / BYTES_PER_MIB;
+  return Number.isInteger(mib) ? `${String(limit)} bytes (${String(mib)} MiB)` : `${String(limit)} bytes`;
+}
+function inputTooLargeError(limit = MAX_INPUT_BYTES) {
+  return new CliError(
+    CLI_CODES.CLI_INPUT_TOO_LARGE,
+    EXIT.DATAERR,
+    `input is larger than the ${describeByteLimit(limit)} this command reads in one invocation; split the input and re-run`
+  );
+}
+
 // src/core/findings.ts
 function formatHl7Position(pos) {
   let out = `seg[${String(pos.segmentIndex)}]`;
@@ -492,11 +534,7 @@ async function validateFormat(format, bytes) {
 }
 async function deframeMllp(bytes) {
   if (bytes.lastIndexOf(11) > bytes.lastIndexOf(28)) {
-    throw new CliError(
-      CLI_CODES.CLI_PARSE_FAILED,
-      EXIT.DATAERR,
-      "truncated MLLP stream: an unterminated frame at the end of input (no closing FS/CR)"
-    );
+    throw truncatedMllpError();
   }
   const { FrameReader } = await loadOptional("mllp", () => import('@cosyte/mllp'));
   const payloads = [];
@@ -508,6 +546,13 @@ async function deframeMllp(bytes) {
   reader.push(Buffer.from(bytes));
   return { payloads, warningCount };
 }
+function truncatedMllpError() {
+  return new CliError(
+    CLI_CODES.CLI_PARSE_FAILED,
+    EXIT.DATAERR,
+    "truncated MLLP stream: an unterminated frame at the end of input (no closing FS/CR)"
+  );
+}
 function decode(bytes) {
   return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
 }
@@ -523,6 +568,84 @@ function unsupportedInternal(format, op) {
   );
 }
 
+// src/core/records.ts
+var LINE_FEED = 10;
+var CARRIAGE_RETURN = 13;
+var VERTICAL_TAB = 11;
+var FILE_SEPARATOR = 28;
+function asBuffer(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.length);
+}
+async function* oneChunk(bytes) {
+  await Promise.resolve();
+  if (bytes.length > 0) yield bytes;
+}
+async function* withinLimit(chunks, limit = MAX_INPUT_BYTES) {
+  let total = 0;
+  for await (const chunk of chunks) {
+    total += chunk.length;
+    if (total > limit) throw inputTooLargeError(limit);
+    yield chunk;
+  }
+}
+async function collectChunks(chunks) {
+  const parts = [];
+  for await (const chunk of chunks) parts.push(asBuffer(chunk));
+  return Buffer.concat(parts);
+}
+function isBlank(line) {
+  return new TextDecoder("utf-8", { fatal: false }).decode(line).trim().length === 0;
+}
+function stripCarriageReturn(line) {
+  return line.length > 0 && line[line.length - 1] === CARRIAGE_RETURN ? line.subarray(0, line.length - 1) : line;
+}
+async function* ndjsonRecords(chunks) {
+  let carry = Buffer.alloc(0);
+  for await (const chunk of chunks) {
+    const buf = carry.length > 0 ? Buffer.concat([carry, asBuffer(chunk)]) : asBuffer(chunk);
+    let start = 0;
+    for (; ; ) {
+      const end = buf.indexOf(LINE_FEED, start);
+      if (end < 0) break;
+      const line = stripCarriageReturn(buf.subarray(start, end));
+      if (!isBlank(line)) yield line;
+      start = end + 1;
+    }
+    carry = start === 0 ? asBuffer(buf) : Buffer.from(buf.subarray(start));
+  }
+  const last = stripCarriageReturn(carry);
+  if (!isBlank(last)) yield last;
+}
+async function* mllpFrames(chunks) {
+  const { FrameReader } = await loadOptional("mllp", () => import('@cosyte/mllp'));
+  const ready = [];
+  const reader = new FrameReader({
+    onFrame: (payload) => ready.push(Buffer.from(payload)),
+    onWarning: () => void 0,
+    // The CLI's own documented input limit is the binding one, so the reader's smaller default frame
+    // ceiling is raised to it: an over-limit MLLP stream is refused by the limit the help output and
+    // the command reference state, not by an undocumented one underneath it.
+    maxFrameSizeBytes: MAX_INPUT_BYTES
+  });
+  let lastStart = -1;
+  let lastEnd = -1;
+  let offset = 0;
+  for await (const chunk of chunks) {
+    const buf = asBuffer(chunk);
+    const start = buf.lastIndexOf(VERTICAL_TAB);
+    if (start >= 0) lastStart = offset + start;
+    const end = buf.lastIndexOf(FILE_SEPARATOR);
+    if (end >= 0) lastEnd = offset + end;
+    offset += buf.length;
+    reader.push(buf);
+    while (ready.length > 0) {
+      const frame = ready.shift();
+      if (frame !== void 0) yield frame;
+    }
+  }
+  if (lastStart > lastEnd) throw truncatedMllpError();
+}
+
 // src/core/input.ts
 async function resolveInput(source, formatOverride, deps, op) {
   if (source === void 0) {
@@ -544,34 +667,91 @@ async function resolveInput(source, formatOverride, deps, op) {
   if (bytes.length === 0) {
     return fail(new CliError(CLI_CODES.CLI_EMPTY_INPUT, EXIT.DATAERR, "input is empty"));
   }
+  const format = resolveFormat(bytes, formatOverride, op);
+  if (format instanceof CliError) return fail(format);
+  return { ok: true, input: { format, bytes } };
+}
+async function resolveInputStream(source, formatOverride, deps, op, limit = MAX_INPUT_BYTES) {
+  if (source === void 0) {
+    return fail(
+      new CliError(
+        CLI_CODES.CLI_USAGE,
+        EXIT.USAGE,
+        "missing <file> argument; pass a path or `-` to read stdin"
+      )
+    );
+  }
+  const iterator = withinLimit(openChunks(source, deps), limit)[Symbol.asyncIterator]();
+  const need = formatOverride === void 0 ? DETECT_PREFIX_BYTES : 1;
+  const head = [];
+  let headBytes = 0;
+  try {
+    while (headBytes < need) {
+      const step = await iterator.next();
+      if (step.done === true) break;
+      head.push(step.value);
+      headBytes += step.value.length;
+    }
+  } catch (e) {
+    if (e instanceof CliError) return fail(e);
+    throw e;
+  }
+  if (headBytes === 0) {
+    return fail(new CliError(CLI_CODES.CLI_EMPTY_INPUT, EXIT.DATAERR, "input is empty"));
+  }
+  const prefix = Buffer.concat(
+    head.map((c) => Buffer.from(c.buffer, c.byteOffset, c.length)),
+    Math.min(headBytes, DETECT_PREFIX_BYTES)
+  );
+  const format = resolveFormat(prefix, formatOverride, op);
+  if (format instanceof CliError) {
+    await iterator.return(void 0);
+    return fail(format);
+  }
+  return { ok: true, input: { format, chunks: rejoin(head, iterator) } };
+}
+function openChunks(source, deps) {
+  if (source === "-") {
+    return deps.openStdin === void 0 ? readerAsChunks(() => deps.readStdin()) : deps.openStdin();
+  }
+  return deps.openFile === void 0 ? readerAsChunks(() => deps.readFile(source)) : deps.openFile(source);
+}
+async function* readerAsChunks(read) {
+  yield* oneChunk(await read());
+}
+async function* rejoin(head, rest) {
+  for (const chunk of head) yield chunk;
+  for (; ; ) {
+    const step = await rest.next();
+    if (step.done === true) return;
+    yield step.value;
+  }
+}
+function resolveFormat(prefix, formatOverride, op) {
   let format;
   if (formatOverride !== void 0) {
     const narrowed = asCosyteFormat(formatOverride);
     if (narrowed === null) {
-      return fail(
-        new CliError(
-          CLI_CODES.CLI_USAGE,
-          EXIT.USAGE,
-          "unknown --format value; expected one of hl7, fhir, dicom, x12, ccda, ncpdp, astm, mllp"
-        )
+      return new CliError(
+        CLI_CODES.CLI_USAGE,
+        EXIT.USAGE,
+        "unknown --format value; expected one of hl7, fhir, dicom, x12, ccda, ncpdp, astm, mllp"
       );
     }
     format = narrowed;
   } else {
-    const detected = detectFormat(bytes);
-    if (detected.format === null) return fail(detectionError(detected));
+    const detected = detectFormat(prefix);
+    if (detected.format === null) return detectionError(detected);
     format = detected.format;
   }
-  if (!supportsOp(format, op)) {
-    return fail(
-      new CliError(
-        CLI_CODES.CLI_FORMAT_UNSUPPORTED,
-        EXIT.DATAERR,
-        `format '${format}' does not support \`${op}\` in this CLI build (${op} supports: ${formatsSupporting(op).join(", ")})`
-      )
+  if (op !== null && !supportsOp(format, op)) {
+    return new CliError(
+      CLI_CODES.CLI_FORMAT_UNSUPPORTED,
+      EXIT.DATAERR,
+      `format '${format}' does not support \`${op}\` in this CLI build (${op} supports: ${formatsSupporting(op).join(", ")})`
     );
   }
-  return { ok: true, input: { format, bytes } };
+  return format;
 }
 function fail(e) {
   return { ok: false, result: errorResult(e) };
@@ -843,11 +1023,24 @@ async function parseCommand(args, deps, posture = VALUE_FREE) {
       )
     );
   }
-  const resolved = await resolveInput(positionals[0], values.format, deps, "parse");
+  const resolved = await resolveInputStream(positionals[0], values.format, deps, "parse");
   if (!resolved.ok) return resolved.result;
-  const { format, bytes } = resolved.input;
+  const { format, chunks } = resolved.input;
   if (format === "mllp" || values.ndjson === true) {
-    return await parseMulti(format, bytes, values.ndjson === true, values.quiet === true);
+    return await parseMulti(
+      format,
+      chunks,
+      values.ndjson === true,
+      values.quiet === true,
+      deps.writeStdout
+    );
+  }
+  let bytes;
+  try {
+    bytes = await collectChunks(chunks);
+  } catch (e) {
+    if (e instanceof CliError) return errorResult(e);
+    throw e;
   }
   return await parseSingle(format, bytes, values.json === true, values.quiet === true, posture);
 }
@@ -866,23 +1059,57 @@ async function parseSingle(format, bytes, json, quiet, posture) {
 ` : "";
   return { stdout, stderr, exit: EXIT.OK };
 }
-async function parseMulti(format, bytes, ndjson, quiet) {
-  let records;
-  let recordFormat;
+async function parseMulti(format, chunks, ndjson, quiet, writeStdout) {
+  const recordFormat = format === "mllp" ? "hl7" : format;
+  const records = format === "mllp" ? mllpFrames(chunks) : ndjsonRecords(chunks);
+  const held = [];
+  const emit = (line) => {
+    if (writeStdout === void 0) {
+      held.push(line);
+      return;
+    }
+    try {
+      writeStdout(line);
+    } catch {
+      throw new CliError(
+        CLI_CODES.CLI_OUTPUT_WRITE_FAILED,
+        EXIT.IOERR,
+        "could not write to the output stream; it closed before the record stream finished"
+      );
+    }
+  };
+  const written = () => held.join("");
+  let total = 0;
+  let failed = 0;
+  let warnings = 0;
   try {
-    if (format === "mllp") {
-      const { payloads } = await deframeMllp(bytes);
-      records = payloads;
-      recordFormat = "hl7";
-    } else {
-      records = splitLines(bytes);
-      recordFormat = format;
+    for await (const record of records) {
+      let line;
+      try {
+        const { model, warnings: ws } = await parseFormat(recordFormat, record);
+        warnings += ws.length;
+        line = { record: total, format: recordFormat, model, warnings: ws };
+      } catch (e) {
+        if (e instanceof CliError) throw e;
+        failed += 1;
+        line = {
+          record: total,
+          format: recordFormat,
+          error: extractStableCode(e) ?? "CLI_PARSE_FAILED"
+        };
+      }
+      total += 1;
+      emit(JSON.stringify(line) + "\n");
     }
   } catch (e) {
-    if (e instanceof CliError) return errorResult(e);
-    return parseFailureResult(format, bytes, VALUE_FREE, e);
+    if (e instanceof CliError) {
+      return { stdout: written(), stderr: `${formatDiagnostic(e)}
+`, exit: e.exit };
+    }
+    const rejected = parseFailureResult(format, new Uint8Array(), VALUE_FREE, e);
+    return { stdout: written(), stderr: rejected.stderr, exit: rejected.exit };
   }
-  if (records.length === 0) {
+  if (total === 0) {
     return errorResult(
       new CliError(
         CLI_CODES.CLI_PARSE_FAILED,
@@ -891,34 +1118,9 @@ async function parseMulti(format, bytes, ndjson, quiet) {
       )
     );
   }
-  const lines = [];
-  let failed = 0;
-  let warnings = 0;
-  for (let i = 0; i < records.length; i += 1) {
-    const rec = records[i];
-    try {
-      const { model, warnings: ws } = await parseFormat(recordFormat, rec);
-      warnings += ws.length;
-      lines.push({ record: i, format: recordFormat, model, warnings: ws });
-    } catch (e) {
-      if (e instanceof CliError) return errorResult(e);
-      failed += 1;
-      lines.push({
-        record: i,
-        format: recordFormat,
-        error: extractStableCode(e) ?? "CLI_PARSE_FAILED"
-      });
-    }
-  }
-  const stdout = lines.map((l) => JSON.stringify(l)).join("\n") + "\n";
   const exit = failed > 0 ? EXIT.DATAERR : EXIT.OK;
-  const stderr = quiet ? "" : `cosyte: parsed ${String(records.length)} ${recordFormat} record(s) (${String(warnings)} warning(s), ${String(failed)} failed)` + (ndjson ? " [ndjson]" : format === "mllp" ? " [mllp]" : "") + "\n";
-  return { stdout, stderr, exit };
-}
-function splitLines(bytes) {
-  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
-  const enc = new TextEncoder();
-  return text.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => enc.encode(line));
+  const stderr = quiet ? "" : `cosyte: parsed ${String(total)} ${recordFormat} record(s) (${String(warnings)} warning(s), ${String(failed)} failed)` + (ndjson ? " [ndjson]" : format === "mllp" ? " [mllp]" : "") + "\n";
+  return { stdout: written(), stderr, exit };
 }
 var VALIDATE_OPTIONS = {
   format: { type: "string" },
@@ -1001,39 +1203,116 @@ var FORMAT_PROP = {
     description: "Optional format override; omit to autodetect by content. A format whose parser does not support the requested operation returns a value-free CLI_FORMAT_UNSUPPORTED (never a fake)."
   }
 };
+var OUTCOME_PROPS = {
+  ok: {
+    type: "boolean",
+    description: "True iff the tool call produced data. A negative verdict about the message is still true (the tool worked); only a call that produced no data at all is false."
+  },
+  status: {
+    type: "string",
+    enum: ["success", "verdict", "failed"],
+    description: "The outcome to branch on without parsing text: 'success' the operation completed cleanly, 'verdict' the tool ran and reports a negative finding about the message, 'failed' the call produced no data (a usage mistake, unparseable input, an unavailable parser, an internal error)."
+  },
+  exit: {
+    type: "integer",
+    enum: Object.values(EXIT),
+    description: "The exit code the underlying command resolved to, from the documented exit-code contract."
+  },
+  code: {
+    type: "string",
+    enum: Object.values(CLI_CODES),
+    description: "The stable diagnostic code on a failed call, drawn from a fixed registry so it never carries an input value. Absent on a call that produced data."
+  }
+};
+var OUTCOME_REQUIRED = ["ok", "status", "exit"];
+function outputSchema(data) {
+  return {
+    type: "object",
+    properties: { ...OUTCOME_PROPS, data },
+    required: [...OUTCOME_REQUIRED],
+    additionalProperties: false
+  };
+}
 var TOOL_DEFS = [
   {
     name: "parse",
+    title: "Parse a healthcare message",
     description: "Parse a healthcare message (HL7 v2 or FHIR R4) to typed JSON. Format is autodetected by content. Returns the parsed model plus value-free warnings.",
     inputSchema: {
       type: "object",
       properties: { ...CONTENT_PROP, ...FORMAT_PROP },
       required: ["content"],
       additionalProperties: false
-    }
+    },
+    outputSchema: outputSchema({
+      type: "object",
+      description: "The parse payload, present on a call that produced data. A single message parses to format + model + warnings. A multi-record input (an MLLP stream) parses to `records`, one entry per record: a parsed record, or a value-free per-record error code.",
+      properties: {
+        format: { type: "string", description: "The format the input was parsed as." },
+        model: { description: "The wrapped library's parsed model, verbatim: the data channel." },
+        warnings: {
+          type: "array",
+          description: "Value-free parse warnings: a stable code plus positional context."
+        },
+        records: {
+          type: "array",
+          description: "One entry per record of a multi-record input, in stream order."
+        }
+      },
+      additionalProperties: false
+    })
   },
   {
     name: "validate",
+    title: "Validate a healthcare message",
     description: "Validate a message and carry the verdict: ok=true with a valid result, or a result reporting value-free findings. The parsed-but-invalid verdict is a successful call (not a tool error).",
     inputSchema: {
       type: "object",
       properties: { ...CONTENT_PROP, ...FORMAT_PROP },
       required: ["content"],
       additionalProperties: false
-    }
+    },
+    outputSchema: outputSchema({
+      type: "object",
+      description: "The validation payload, present on a call that produced data (a valid result and a negative verdict alike). Value-free throughout: findings are codes, severities and positional locators, never a field value.",
+      properties: {
+        format: { type: "string", description: "The format the input was validated as." },
+        valid: {
+          type: "boolean",
+          description: "The verdict: false means parsed-but-non-conformant, not a failed call."
+        },
+        findings: {
+          type: "array",
+          description: "Value-free findings: a stable code, a severity, and a positional locator."
+        }
+      },
+      required: ["format", "valid", "findings"],
+      additionalProperties: false
+    })
   },
   {
     name: "inspect",
+    title: "Inspect a healthcare message's structure",
     description: "Return a value-free structural summary of a message: its type, segment/entry counts, and a warning/issue count. Never includes a field value.",
     inputSchema: {
       type: "object",
       properties: { ...CONTENT_PROP, ...FORMAT_PROP },
       required: ["content"],
       additionalProperties: false
-    }
+    },
+    outputSchema: outputSchema({
+      type: "object",
+      description: "The value-free structural summary, present on a call that produced data. `format` names the shape of the rest, which is that format's own counts and structural type codes (a message type, a resource type, a transaction-set id): classification, never a value.",
+      properties: {
+        format: { type: "string", description: "The format the summary describes." }
+      },
+      required: ["format"],
+      additionalProperties: true
+    })
   },
   {
     name: "convert",
+    title: "Convert HL7 v2 to a FHIR R4 Bundle",
     description: "Convert an HL7 v2 message to a FHIR R4 Bundle via @cosyte/transform. Returns the converted Bundle; an error-severity conversion issue is reported with ok=false.",
     inputSchema: {
       type: "object",
@@ -1047,7 +1326,21 @@ var TOOL_DEFS = [
       },
       required: ["content"],
       additionalProperties: false
-    }
+    },
+    outputSchema: outputSchema({
+      type: "object",
+      description: "The conversion payload, present on a call that produced data. An error-severity finding is a negative verdict (the Bundle is still returned), not a failed call.",
+      properties: {
+        format: { type: "string", description: "The conversion target the Bundle is in." },
+        bundle: { type: "object", description: "The converted FHIR R4 Bundle: the data channel." },
+        findings: {
+          type: "array",
+          description: "Value-free conversion findings: a code, a severity, and a positional locator."
+        }
+      },
+      required: ["format", "bundle", "findings"],
+      additionalProperties: false
+    })
   }
 ];
 function inlineDeps(content) {
@@ -1068,37 +1361,65 @@ function stringArg(args, key) {
   const v = args[key];
   return typeof v === "string" ? v : null;
 }
-function toToolResult(result) {
-  const hardError = result.stdout === "";
-  const text = hardError ? result.stderr.trim() : result.stdout.trim();
+function structuredResult(structuredContent) {
   return {
-    content: [
-      { type: "text", text: text.length > 0 ? text : `cosyte: exit ${String(result.exit)}` }
-    ],
-    isError: hardError,
-    structuredContent: { exit: result.exit, ok: !hardError }
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    isError: structuredContent.status === "failed",
+    structuredContent
   };
 }
-function usageError(message) {
-  return {
-    content: [{ type: "text", text: `cosyte: ${CLI_CODES.CLI_USAGE}: ${message}` }],
-    isError: true,
-    structuredContent: { exit: EXIT.USAGE, ok: false }
-  };
+function isRecordLine(value) {
+  return typeof value === "object" && value !== null && "record" in value;
+}
+function parsePayload(stdout) {
+  const values = [];
+  for (const line of stdout.split("\n")) {
+    if (line.trim().length === 0) continue;
+    try {
+      values.push(JSON.parse(line));
+    } catch {
+      return void 0;
+    }
+  }
+  const only = values.length === 1 ? values[0] : void 0;
+  return only !== void 0 && !isRecordLine(only) ? only : { records: values };
+}
+function diagnosticCode(stderr) {
+  return Object.values(CLI_CODES).find((code) => stderr.includes(`cosyte: ${code}: `));
+}
+function toToolResult(result) {
+  if (result.stdout === "") {
+    const code = diagnosticCode(result.stderr);
+    return structuredResult({
+      ok: false,
+      status: "failed",
+      exit: result.exit,
+      ...code !== void 0 ? { code } : {}
+    });
+  }
+  const data = parsePayload(result.stdout);
+  return structuredResult({
+    ok: true,
+    status: result.exit === EXIT.OK ? "success" : "verdict",
+    exit: result.exit,
+    ...data !== void 0 ? { data } : {}
+  });
+}
+function usageError() {
+  return structuredResult({
+    ok: false,
+    status: "failed",
+    exit: EXIT.USAGE,
+    code: CLI_CODES.CLI_USAGE
+  });
 }
 function internalError(e) {
   const err = toCliError(e);
-  return {
-    content: [{ type: "text", text: `cosyte: ${err.code}: ${err.message}` }],
-    isError: true,
-    structuredContent: { exit: err.exit, ok: false }
-  };
+  return structuredResult({ ok: false, status: "failed", exit: err.exit, code: err.code });
 }
 async function dispatchTool(name, args, deps) {
   const content = stringArg(args, "content");
-  if (content === null) {
-    return usageError("missing required 'content' argument (the message text to operate on)");
-  }
+  if (content === null) return usageError();
   const runDeps = inlineDeps(content);
   const format = stringArg(args, "format");
   const fmtFlag = format !== null ? ["--format", format] : [];
@@ -1117,7 +1438,7 @@ async function dispatchTool(name, args, deps) {
         return toToolResult(await convertCommand(["-", "--to", to, "--json"], runDeps, VALUE_FREE));
       }
       default:
-        return usageError(`unknown tool '${name}'`);
+        return usageError();
     }
   } catch (e) {
     return internalError(e);
@@ -1131,12 +1452,21 @@ function createMcpServer() {
   server.setRequestHandler(ListToolsRequestSchema, () => ({
     tools: TOOL_DEFS.map((t) => ({
       name: t.name,
+      title: t.title,
       description: t.description,
       inputSchema: {
         type: t.inputSchema.type,
         properties: { ...t.inputSchema.properties },
         ...t.inputSchema.required !== void 0 ? { required: [...t.inputSchema.required] } : {},
         ...t.inputSchema.additionalProperties !== void 0 ? { additionalProperties: t.inputSchema.additionalProperties } : {}
+      },
+      // Every advertised tool publishes its result schema; a client validates a reply against it
+      // instead of pattern-matching the text block. Declared, so it is copied unconditionally.
+      outputSchema: {
+        type: t.outputSchema.type,
+        properties: { ...t.outputSchema.properties },
+        required: [...t.outputSchema.required],
+        additionalProperties: t.outputSchema.additionalProperties
       }
     }))
   }));
@@ -1146,7 +1476,9 @@ function createMcpServer() {
     return {
       content: result.content.map((c) => ({ type: c.type, text: c.text })),
       isError: result.isError,
-      structuredContent: { exit: result.structuredContent.exit, ok: result.structuredContent.ok }
+      // The whole structured value reaches the wire. A field-by-field copy here would silently
+      // truncate the payload the called tool's own schema promises.
+      structuredContent: { ...result.structuredContent }
     };
   });
   return server;
@@ -1157,8 +1489,31 @@ async function startStdioServer() {
 }
 
 // src/bin/cosyte-mcp.ts
+var stderrOpen = true;
+var reported = false;
+process.stderr.on("error", () => {
+  stderrOpen = false;
+});
+function note(line) {
+  if (!stderrOpen) return;
+  try {
+    process.stderr.write(line);
+  } catch {
+    stderrOpen = false;
+  }
+}
+process.stdout.on("error", () => {
+  if (reported) return;
+  reported = true;
+  note(
+    `cosyte-mcp: ${CLI_CODES.CLI_OUTPUT_WRITE_FAILED}: could not write to the output stream; it closed before the output was delivered
+`
+  );
+  process.exitCode = EXIT.IOERR;
+  process.stdin.destroy();
+});
 startStdioServer().catch(() => {
-  process.stderr.write("cosyte-mcp: CLI_INTERNAL: the MCP server failed to start\n");
+  note("cosyte-mcp: CLI_INTERNAL: the MCP server failed to start\n");
   process.exitCode = 70;
 });
 //# sourceMappingURL=cosyte-mcp.mjs.map