octoflow-core 1.0.0

package/dist/output/parse.js

@@ -0,0 +1,246 @@
+import { assertNever } from "../utils/assert-never.js";
+function parseResponse(text, schema) {
+  const errors = [];
+  const value = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const parsed = parseField(text, key, lift(field), key);
+    if (parsed.ok) {
+      value[key] = parsed.value;
+    } else {
+      errors.push(...parsed.errors);
+    }
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, value };
+}
+function hasKind(field) {
+  return typeof field === "object" && field != null && "kind" in field;
+}
+function lift(field) {
+  if (hasKind(field)) return field;
+  const fields = {};
+  for (const [key, sub] of Object.entries(field)) {
+    fields[key] = lift(sub);
+  }
+  return { kind: "object", fields };
+}
+function parseField(text, label, field, path) {
+  switch (field.kind) {
+    case "integer":
+    case "number":
+      return parseNumeric(text, label, field, path);
+    case "string":
+      return parseString(text, label, field, path);
+    case "enum":
+      return parseEnum(text, label, field, path);
+    case "boolean":
+      return parseBoolean(text, label, path);
+    case "list":
+      return parseList(text, label, field, path);
+    case "object": {
+      const errors = [];
+      const value = {};
+      for (const [key, sub] of Object.entries(field.fields)) {
+        const childPath = `${path}.${key}`;
+        const parsed = parseField(text, key, sub, childPath);
+        if (parsed.ok) value[key] = parsed.value;
+        else errors.push(...parsed.errors);
+      }
+      if (errors.length > 0) return { ok: false, errors };
+      return { ok: true, value };
+    }
+    default:
+      return assertNever(field, "parseField");
+  }
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function parseNumeric(text, label, field, path) {
+  const safe = escapeRegExp(label);
+  const patterns = [
+    // "label: **7**" / "label: 7" / "label: 7/10" / "label - 7/10"
+    new RegExp(
+      `${safe}\\s*[:\\-\u2014]\\s*(?:\\*\\*)?\\s*(-?\\d+(?:\\.\\d+)?)(?:\\s*/\\s*10)?\\s*(?:\\*\\*)?`,
+      "i"
+    ),
+    // "label — 7 out of 10" / "label ... 7 out of 10"
+    new RegExp(
+      `${safe}[^\\d\\n]{0,20}(-?\\d+(?:\\.\\d+)?)\\s*out\\s+of\\s*\\d+`,
+      "i"
+    ),
+    // "label ... 7/10"
+    new RegExp(`${safe}[^\\d\\n]{0,20}(-?\\d+(?:\\.\\d+)?)\\s*/\\s*10`, "i"),
+    // bare digit within 20 non-digit chars of the label
+    new RegExp(`${safe}[^\\d\\n]{0,20}(-?\\d+(?:\\.\\d+)?)`, "i")
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (!match || match[1] == null) continue;
+    const raw = field.kind === "integer" ? parseInt(match[1], 10) : parseFloat(match[1]);
+    if (Number.isNaN(raw)) continue;
+    if (field.range) {
+      const [min, max] = field.range;
+      if (raw < min || raw > max) {
+        return {
+          ok: false,
+          errors: [
+            {
+              path,
+              code: "out-of-range",
+              message: `expected ${field.kind} in [${min}, ${max}] at ${path}, got ${raw}`,
+              sample: match[0]
+            }
+          ]
+        };
+      }
+    }
+    return { ok: true, value: raw };
+  }
+  return {
+    ok: false,
+    errors: [
+      {
+        path,
+        code: "not-found",
+        message: `no ${field.kind} value found for "${label}"`
+      }
+    ]
+  };
+}
+function parseString(text, label, field, path) {
+  const safe = escapeRegExp(label);
+  const pattern = new RegExp(`${safe}\\s*[:\\-\u2014]\\s*([^\\n]+)`, "i");
+  const match = text.match(pattern);
+  if (!match || match[1] == null) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path,
+          code: "not-found",
+          message: `no string value found for "${label}"`
+        }
+      ]
+    };
+  }
+  const value = match[1].trim();
+  if (field.minLength != null && value.length < field.minLength) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path,
+          code: "out-of-range",
+          message: `string at ${path} shorter than minLength ${field.minLength}`,
+          sample: value
+        }
+      ]
+    };
+  }
+  return { ok: true, value };
+}
+function parseEnum(text, label, field, path) {
+  if (field.options.length === 0) {
+    return {
+      ok: false,
+      errors: [
+        { path, code: "wrong-type", message: `enum at ${path} has no options` }
+      ]
+    };
+  }
+  const ordered = [...field.options].sort((a, b) => b.length - a.length);
+  const escaped = ordered.map(escapeRegExp).join("|");
+  const safe = escapeRegExp(label);
+  const labelled = text.match(
+    new RegExp(`${safe}\\s*[:\\-\u2014]\\s*(${escaped})`, "i")
+  );
+  if (labelled && labelled[1]) {
+    const found = ordered.find(
+      (opt) => opt.toLowerCase() === labelled[1].toLowerCase()
+    );
+    if (found) return { ok: true, value: found };
+  }
+  const anywhere = text.match(new RegExp(`\\b(${escaped})\\b`, "i"));
+  if (anywhere && anywhere[1]) {
+    const found = ordered.find(
+      (opt) => opt.toLowerCase() === anywhere[1].toLowerCase()
+    );
+    if (found) return { ok: true, value: found };
+  }
+  return {
+    ok: false,
+    errors: [
+      {
+        path,
+        code: "not-found",
+        message: `no enum option for "${label}" (expected one of: ${field.options.join(", ")})`
+      }
+    ]
+  };
+}
+function parseBoolean(text, label, path) {
+  const safe = escapeRegExp(label);
+  const match = text.match(
+    new RegExp(`${safe}\\s*[:\\-\u2014]\\s*(true|false|yes|no|1|0|on|off)\\b`, "i")
+  );
+  if (!match || match[1] == null) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path,
+          code: "not-found",
+          message: `no boolean value found for "${label}"`
+        }
+      ]
+    };
+  }
+  const normalised = match[1].toLowerCase();
+  const truthy = /* @__PURE__ */ new Set(["true", "yes", "1", "on"]);
+  return { ok: true, value: truthy.has(normalised) };
+}
+function parseList(text, label, field, path) {
+  const heading = field.heading ?? label;
+  const items = extractBullets(text, heading);
+  if (items.length === 0) {
+    return {
+      ok: false,
+      errors: [
+        {
+          path,
+          code: "not-found",
+          message: `no bullet list found under heading "${heading}"`
+        }
+      ]
+    };
+  }
+  const inner = field.of;
+  if (inner.kind === "string") {
+    return { ok: true, value: items };
+  }
+  const errors = [];
+  const out = [];
+  for (let i = 0; i < items.length; i++) {
+    const childPath = `${path}[${i}]`;
+    const child = parseField(items[i] ?? "", label, inner, childPath);
+    if (child.ok) out.push(child.value);
+    else errors.push(...child.errors);
+  }
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, value: out };
+}
+function extractBullets(text, heading) {
+  const safe = escapeRegExp(heading);
+  const pattern = new RegExp(
+    `${safe}[^\\n]*\\n((?:[ \\t]*[-*\u2022][ \\t]+[^\\n]+\\n?)+)`,
+    "i"
+  );
+  const match = text.match(pattern);
+  if (!match || !match[1]) return [];
+  return match[1].split("\n").map((line) => line.replace(/^[ \t]*[-*•][ \t]+/, "").trim()).filter(Boolean);
+}
+export {
+  parseResponse
+};
+//# sourceMappingURL=parse.js.map

package/dist/output/parse.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/output/parse.ts"],
+  "sourcesContent": ["/**\n * `parseResponse` \u2014 extract a typed value from free-form LLM text against a\n * {@link ResponseSchema}. No silent fallbacks: anything that fails to parse\n * becomes a `{ ok: false, errors: [...] }` result so callers can retry,\n * escalate, or log deliberately.\n *\n * Heuristics were cross-validated against the regex cascades consolidated in\n * `octoflow-examples/src/multi-agent-communication/_shared/council-scoring.ts` (RFC \u00A74.3.6) so\n * migrated council/rater templates preserve their tolerance matrix.\n */\n\nimport { assertNever } from '../utils/assert-never.js';\nimport type {\n  FieldSchema,\n  InferSchema,\n  ParseError,\n  ParseResult,\n  PrimitiveSchema,\n  ResponseSchema,\n  SchemaField,\n} from './types.js';\n\nexport function parseResponse<S extends ResponseSchema>(\n  text: string,\n  schema: S\n): ParseResult<InferSchema<S>> {\n  const errors: ParseError[] = [];\n  const value: Record<string, unknown> = {};\n\n  for (const [key, field] of Object.entries(schema)) {\n    const parsed = parseField(text, key, lift(field), key);\n    if (parsed.ok) {\n      value[key] = parsed.value;\n    } else {\n      errors.push(...parsed.errors);\n    }\n  }\n\n  if (errors.length > 0) return { ok: false, errors };\n  return { ok: true, value: value as InferSchema<S> };\n}\n\nfunction hasKind(field: SchemaField): field is FieldSchema {\n  return typeof field === 'object' && field != null && 'kind' in field;\n}\n\n/** Auto-lift a bare record into `{ kind: 'object', fields: ... }`. */\nfunction lift(field: SchemaField): FieldSchema {\n  if (hasKind(field)) return field;\n  const fields: Record<string, FieldSchema> = {};\n  for (const [key, sub] of Object.entries(field)) {\n    fields[key] = lift(sub);\n  }\n  return { kind: 'object', fields };\n}\n\nfunction parseField(\n  text: string,\n  label: string,\n  field: FieldSchema,\n  path: string\n): ParseResult<unknown> {\n  switch (field.kind) {\n    case 'integer':\n    case 'number':\n      return parseNumeric(text, label, field, path);\n    case 'string':\n      return parseString(text, label, field, path);\n    case 'enum':\n      return parseEnum(text, label, field, path);\n    case 'boolean':\n      return parseBoolean(text, label, path);\n    case 'list':\n      return parseList(text, label, field, path);\n    case 'object': {\n      const errors: ParseError[] = [];\n      const value: Record<string, unknown> = {};\n      for (const [key, sub] of Object.entries(field.fields)) {\n        const childPath = `${path}.${key}`;\n        const parsed = parseField(text, key, sub, childPath);\n        if (parsed.ok) value[key] = parsed.value;\n        else errors.push(...parsed.errors);\n      }\n      if (errors.length > 0) return { ok: false, errors };\n      return { ok: true, value };\n    }\n    default:\n      return assertNever(field, 'parseField');\n  }\n}\n\nfunction escapeRegExp(value: string): string {\n  return value.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\nfunction parseNumeric(\n  text: string,\n  label: string,\n  field: Extract<PrimitiveSchema, { kind: 'integer' | 'number' }>,\n  path: string\n): ParseResult<number> {\n  const safe = escapeRegExp(label);\n  // Ordered most-specific \u2192 most-permissive. Mirrors the cascade in\n  // `octoflow-examples/src/multi-agent-communication/_shared/council-scoring.ts::extractAxisScore`.\n  const patterns = [\n    // \"label: **7**\" / \"label: 7\" / \"label: 7/10\" / \"label - 7/10\"\n    new RegExp(\n      `${safe}\\\\s*[:\\\\-\u2014]\\\\s*(?:\\\\*\\\\*)?\\\\s*(-?\\\\d+(?:\\\\.\\\\d+)?)(?:\\\\s*/\\\\s*10)?\\\\s*(?:\\\\*\\\\*)?`,\n      'i'\n    ),\n    // \"label \u2014 7 out of 10\" / \"label ... 7 out of 10\"\n    new RegExp(\n      `${safe}[^\\\\d\\\\n]{0,20}(-?\\\\d+(?:\\\\.\\\\d+)?)\\\\s*out\\\\s+of\\\\s*\\\\d+`,\n      'i'\n    ),\n    // \"label ... 7/10\"\n    new RegExp(`${safe}[^\\\\d\\\\n]{0,20}(-?\\\\d+(?:\\\\.\\\\d+)?)\\\\s*/\\\\s*10`, 'i'),\n    // bare digit within 20 non-digit chars of the label\n    new RegExp(`${safe}[^\\\\d\\\\n]{0,20}(-?\\\\d+(?:\\\\.\\\\d+)?)`, 'i'),\n  ];\n\n  for (const pattern of patterns) {\n    const match = text.match(pattern);\n    if (!match || match[1] == null) continue;\n    const raw =\n      field.kind === 'integer' ? parseInt(match[1], 10) : parseFloat(match[1]);\n    if (Number.isNaN(raw)) continue;\n    if (field.range) {\n      const [min, max] = field.range;\n      if (raw < min || raw > max) {\n        return {\n          ok: false,\n          errors: [\n            {\n              path,\n              code: 'out-of-range',\n              message: `expected ${field.kind} in [${min}, ${max}] at ${path}, got ${raw}`,\n              sample: match[0],\n            },\n          ],\n        };\n      }\n    }\n    return { ok: true, value: raw };\n  }\n\n  return {\n    ok: false,\n    errors: [\n      {\n        path,\n        code: 'not-found',\n        message: `no ${field.kind} value found for \"${label}\"`,\n      },\n    ],\n  };\n}\n\nfunction parseString(\n  text: string,\n  label: string,\n  field: Extract<PrimitiveSchema, { kind: 'string' }>,\n  path: string\n): ParseResult<string> {\n  const safe = escapeRegExp(label);\n  // Matches `label: <rest of line>` \u2014 the only form supported for now;\n  // callers with richer needs should use a `list` or `object` schema.\n  const pattern = new RegExp(`${safe}\\\\s*[:\\\\-\u2014]\\\\s*([^\\\\n]+)`, 'i');\n  const match = text.match(pattern);\n  if (!match || match[1] == null) {\n    return {\n      ok: false,\n      errors: [\n        {\n          path,\n          code: 'not-found',\n          message: `no string value found for \"${label}\"`,\n        },\n      ],\n    };\n  }\n  const value = match[1].trim();\n  if (field.minLength != null && value.length < field.minLength) {\n    return {\n      ok: false,\n      errors: [\n        {\n          path,\n          code: 'out-of-range',\n          message: `string at ${path} shorter than minLength ${field.minLength}`,\n          sample: value,\n        },\n      ],\n    };\n  }\n  return { ok: true, value };\n}\n\nfunction parseEnum(\n  text: string,\n  label: string,\n  field: Extract<PrimitiveSchema, { kind: 'enum' }>,\n  path: string\n): ParseResult<string> {\n  if (field.options.length === 0) {\n    return {\n      ok: false,\n      errors: [\n        { path, code: 'wrong-type', message: `enum at ${path} has no options` },\n      ],\n    };\n  }\n  // Longest-first so `approve-with-changes` wins over `approve`.\n  const ordered = [...field.options].sort((a, b) => b.length - a.length);\n  const escaped = ordered.map(escapeRegExp).join('|');\n  const safe = escapeRegExp(label);\n\n  // 1. Labeled form: `<label>: <option>`.\n  const labelled = text.match(\n    new RegExp(`${safe}\\\\s*[:\\\\-\u2014]\\\\s*(${escaped})`, 'i')\n  );\n  if (labelled && labelled[1]) {\n    const found = ordered.find(\n      (opt) => opt.toLowerCase() === labelled[1]!.toLowerCase()\n    );\n    if (found) return { ok: true, value: found };\n  }\n  // 2. Bare option appearing anywhere in the text.\n  const anywhere = text.match(new RegExp(`\\\\b(${escaped})\\\\b`, 'i'));\n  if (anywhere && anywhere[1]) {\n    const found = ordered.find(\n      (opt) => opt.toLowerCase() === anywhere[1]!.toLowerCase()\n    );\n    if (found) return { ok: true, value: found };\n  }\n  return {\n    ok: false,\n    errors: [\n      {\n        path,\n        code: 'not-found',\n        message: `no enum option for \"${label}\" (expected one of: ${field.options.join(', ')})`,\n      },\n    ],\n  };\n}\n\nfunction parseBoolean(\n  text: string,\n  label: string,\n  path: string\n): ParseResult<boolean> {\n  const safe = escapeRegExp(label);\n  const match = text.match(\n    new RegExp(`${safe}\\\\s*[:\\\\-\u2014]\\\\s*(true|false|yes|no|1|0|on|off)\\\\b`, 'i')\n  );\n  if (!match || match[1] == null) {\n    return {\n      ok: false,\n      errors: [\n        {\n          path,\n          code: 'not-found',\n          message: `no boolean value found for \"${label}\"`,\n        },\n      ],\n    };\n  }\n  const normalised = match[1].toLowerCase();\n  const truthy = new Set(['true', 'yes', '1', 'on']);\n  return { ok: true, value: truthy.has(normalised) };\n}\n\nfunction parseList(\n  text: string,\n  label: string,\n  field: Extract<FieldSchema, { kind: 'list' }>,\n  path: string\n): ParseResult<unknown[]> {\n  const heading = field.heading ?? label;\n  const items = extractBullets(text, heading);\n  if (items.length === 0) {\n    return {\n      ok: false,\n      errors: [\n        {\n          path,\n          code: 'not-found',\n          message: `no bullet list found under heading \"${heading}\"`,\n        },\n      ],\n    };\n  }\n\n  const inner = field.of;\n  // For string / primitive items we just hand each bullet straight back.\n  if (inner.kind === 'string') {\n    return { ok: true, value: items };\n  }\n\n  // For non-string inner schemas we parse each bullet as its own text blob.\n  const errors: ParseError[] = [];\n  const out: unknown[] = [];\n  for (let i = 0; i < items.length; i++) {\n    const childPath = `${path}[${i}]`;\n    const child = parseField(items[i] ?? '', label, inner, childPath);\n    if (child.ok) out.push(child.value);\n    else errors.push(...child.errors);\n  }\n  if (errors.length > 0) return { ok: false, errors };\n  return { ok: true, value: out };\n}\n\nfunction extractBullets(text: string, heading: string): string[] {\n  const safe = escapeRegExp(heading);\n  const pattern = new RegExp(\n    `${safe}[^\\\\n]*\\\\n((?:[ \\\\t]*[-*\u2022][ \\\\t]+[^\\\\n]+\\\\n?)+)`,\n    'i'\n  );\n  const match = text.match(pattern);\n  if (!match || !match[1]) return [];\n  return match[1]\n    .split('\\n')\n    .map((line) => line.replace(/^[ \\t]*[-*\u2022][ \\t]+/, '').trim())\n    .filter(Boolean);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/output/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Schema shape for `defineResponseSchema` / `parseResponse`.
+ *
+ * Deliberately tiny and dependency-free (§5.3 of
+ * RFC-public-api-dx-trio). A generic JSON-schema validator is overkill for
+ * the LLM-output domain; what callers need is a parser that tolerates
+ * formatting drift (prose before/after, `: 8`, `: 8/10`, `— 8 out of 10`,
+ * bold markers, etc.) and reports *where* extraction failed.
+ */
+/** Primitive field — the leaves of a response schema. */
+export type PrimitiveSchema = {
+    kind: 'integer';
+    range?: readonly [number, number];
+} | {
+    kind: 'number';
+    range?: readonly [number, number];
+} | {
+    kind: 'string';
+    minLength?: number;
+} | {
+    kind: 'enum';
+    options: readonly string[];
+} | {
+    kind: 'boolean';
+};
+/** Full field-level schema — primitive, list, or nested object. */
+export type FieldSchema = PrimitiveSchema | {
+    kind: 'list';
+    of: FieldSchema;
+    heading?: string;
+} | {
+    kind: 'object';
+    fields: Record<string, FieldSchema>;
+};
+/**
+ * Input shape: top-level is `Record<string, FieldSchema | NestedRecord>`.
+ * Nested plain records auto-lift to `{ kind: 'object', fields: ... }` so
+ * callers can write
+ *   `scores: { clarity: { kind: 'integer', range: [1, 10] } }`
+ * instead of
+ *   `scores: { kind: 'object', fields: { clarity: ... } }`.
+ */
+export type SchemaField = FieldSchema | {
+    [key: string]: SchemaField;
+};
+export type ResponseSchema = Record<string, SchemaField>;
+export type InferPrimitive<P> = P extends {
+    kind: 'integer';
+} ? number : P extends {
+    kind: 'number';
+} ? number : P extends {
+    kind: 'string';
+} ? string : P extends {
+    kind: 'enum';
+    options: readonly (infer U)[];
+} ? U : P extends {
+    kind: 'boolean';
+} ? boolean : never;
+export type InferField<F> = F extends PrimitiveSchema ? InferPrimitive<F> : F extends {
+    kind: 'list';
+    of: infer E;
+} ? Array<InferField<E>> : F extends {
+    kind: 'object';
+    fields: infer Fields;
+} ? {
+    [K in keyof Fields]: InferField<Fields[K]>;
+} : F extends Record<string, SchemaField> ? {
+    [K in keyof F]: InferField<F[K]>;
+} : never;
+export type InferSchema<S extends ResponseSchema> = {
+    [K in keyof S]: InferField<S[K]>;
+};
+export type ParseErrorCode = 'not-found' | 'out-of-range' | 'wrong-type';
+export interface ParseError {
+    /** Dotted path to the offending field (e.g. `"scores.clarity"`). */
+    path: string;
+    code: ParseErrorCode;
+    /** Short human-readable note for logs. */
+    message: string;
+    /** Excerpt of the input near the failure, when available. */
+    sample?: string;
+}
+export type ParseResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: ParseError[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/output/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/output/types.ts"],"names":[],"mappings":"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"}

package/dist/output/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/output/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/output/validated-worker.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `createValidatedWorker` — schema-bound convenience wrapper around any
+ * `ask`-like text primitive (e.g. `pack.sendMessage`, `bridge.sendMessage`,
+ * a direct API client). On parse failure the worker re-asks with a
+ * schema-drift hint, up to `retries` times.
+ *
+ * Kept transport-agnostic so callers can reuse it with Bridge, Pack, or any
+ * plain `(prompt) => Promise<string>` adapter.
+ *
+ * Ships per RFC-public-api-dx-trio §4.3.3.
+ */
+import { OctoFlowError } from '../domain/errors/base.js';
+import type { InferSchema, ParseError, ParseResult, ResponseSchema } from './types.js';
+/** A minimal `ask(prompt) → text` function the validated worker wraps. */
+export type AskFn = (prompt: string) => Promise<string>;
+export type ParseErrorMode = 'return-partial' | 'retry' | 'throw';
+export interface ValidatedWorkerOptions<S extends ResponseSchema> {
+    /** Underlying text-producer (Pack/Bridge/plain API). */
+    ask: AskFn;
+    /** Schema to validate each response against. */
+    schema: S;
+    /**
+     * How many re-asks to attempt after the first parse failure. Default 0
+     * (single-shot). The retry prompt embeds a schema-drift hint derived from
+     * {@link describeSchemaForLLM}.
+     */
+    retries?: number;
+    /**
+     * What to do when retries are exhausted:
+     *   - `'return-partial'` (default): return `{ ok: false, errors }`.
+     *   - `'throw'`: throw a {@link ValidatedWorkerParseError}.
+     *   - `'retry'`: alias for `'return-partial'` after retries run out.
+     */
+    onParseError?: ParseErrorMode;
+}
+export interface ValidatedWorker<S extends ResponseSchema> {
+    ask(prompt: string): Promise<ParseResult<InferSchema<S>>>;
+}
+/**
+ * Thrown when `onParseError: 'throw'` and parsing fails after all retries.
+ * Carries the full `errors` array so operators can log provenance.
+ */
+export declare class ValidatedWorkerParseError extends OctoFlowError {
+    readonly errors: ParseError[];
+    constructor(message: string, errors: ParseError[]);
+}
+export declare function createValidatedWorker<S extends ResponseSchema>(opts: ValidatedWorkerOptions<S>): ValidatedWorker<S>;
+//# sourceMappingURL=validated-worker.d.ts.map

package/dist/output/validated-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validated-worker.d.ts","sourceRoot":"","sources":["../../src/output/validated-worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAElE,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,cAAc;IAC9D,wDAAwD;IACxD,GAAG,EAAE,KAAK,CAAC;IACX,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC;IACV;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,cAAc;IACvD,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC3D;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,aAAa;IAC1D,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;gBAClB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE;CAOlD;AAOD,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,cAAc,EAC5D,IAAI,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAC9B,eAAe,CAAC,CAAC,CAAC,CA0BpB"}

package/dist/output/validated-worker.js

@@ -0,0 +1,59 @@
+import { OctoFlowError, registerErrorClass } from "../domain/errors/base.js";
+import { describeSchemaForLLM } from "./describe.js";
+import { parseResponse } from "./parse.js";
+class ValidatedWorkerParseError extends OctoFlowError {
+  errors;
+  constructor(message, errors) {
+    super("VALIDATED_WORKER_PARSE_ERROR", message, {
+      errorCount: errors.length
+    });
+    this.name = "ValidatedWorkerParseError";
+    this.errors = errors;
+  }
+}
+registerErrorClass(
+  "VALIDATED_WORKER_PARSE_ERROR",
+  (payload) => new ValidatedWorkerParseError(payload.message, [])
+);
+function createValidatedWorker(opts) {
+  const retries = opts.retries ?? 0;
+  const mode = opts.onParseError ?? "return-partial";
+  return {
+    async ask(prompt) {
+      let lastResult;
+      let currentPrompt = prompt;
+      for (let attempt = 0; attempt <= retries; attempt++) {
+        const text = await opts.ask(currentPrompt);
+        const parsed = parseResponse(text, opts.schema);
+        if (parsed.ok) return parsed;
+        lastResult = parsed;
+        if (attempt < retries) {
+          currentPrompt = buildRetryPrompt(prompt, opts.schema, parsed.errors);
+        }
+      }
+      if (mode === "throw") {
+        throw new ValidatedWorkerParseError(
+          `validatedWorker: response did not match schema after ${retries + 1} attempt(s)`,
+          lastResult?.ok === false ? lastResult.errors : []
+        );
+      }
+      return lastResult ?? { ok: false, errors: [] };
+    }
+  };
+}
+function buildRetryPrompt(original, schema, errors) {
+  const summary = errors.map((e) => `  \u2022 ${e.path}: ${e.code}`).join("\n");
+  return [
+    original,
+    "",
+    "Your last response did not match the expected schema:",
+    summary,
+    "",
+    describeSchemaForLLM(schema)
+  ].join("\n");
+}
+export {
+  ValidatedWorkerParseError,
+  createValidatedWorker
+};
+//# sourceMappingURL=validated-worker.js.map

package/dist/output/validated-worker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/output/validated-worker.ts"],
+  "sourcesContent": ["/**\n * `createValidatedWorker` \u2014 schema-bound convenience wrapper around any\n * `ask`-like text primitive (e.g. `pack.sendMessage`, `bridge.sendMessage`,\n * a direct API client). On parse failure the worker re-asks with a\n * schema-drift hint, up to `retries` times.\n *\n * Kept transport-agnostic so callers can reuse it with Bridge, Pack, or any\n * plain `(prompt) => Promise<string>` adapter.\n *\n * Ships per RFC-public-api-dx-trio \u00A74.3.3.\n */\n\nimport { OctoFlowError, registerErrorClass } from '../domain/errors/base.js';\nimport { describeSchemaForLLM } from './describe.js';\nimport { parseResponse } from './parse.js';\nimport type {\n  InferSchema,\n  ParseError,\n  ParseResult,\n  ResponseSchema,\n} from './types.js';\n\n/** A minimal `ask(prompt) \u2192 text` function the validated worker wraps. */\nexport type AskFn = (prompt: string) => Promise<string>;\n\nexport type ParseErrorMode = 'return-partial' | 'retry' | 'throw';\n\nexport interface ValidatedWorkerOptions<S extends ResponseSchema> {\n  /** Underlying text-producer (Pack/Bridge/plain API). */\n  ask: AskFn;\n  /** Schema to validate each response against. */\n  schema: S;\n  /**\n   * How many re-asks to attempt after the first parse failure. Default 0\n   * (single-shot). The retry prompt embeds a schema-drift hint derived from\n   * {@link describeSchemaForLLM}.\n   */\n  retries?: number;\n  /**\n   * What to do when retries are exhausted:\n   *   - `'return-partial'` (default): return `{ ok: false, errors }`.\n   *   - `'throw'`: throw a {@link ValidatedWorkerParseError}.\n   *   - `'retry'`: alias for `'return-partial'` after retries run out.\n   */\n  onParseError?: ParseErrorMode;\n}\n\nexport interface ValidatedWorker<S extends ResponseSchema> {\n  ask(prompt: string): Promise<ParseResult<InferSchema<S>>>;\n}\n\n/**\n * Thrown when `onParseError: 'throw'` and parsing fails after all retries.\n * Carries the full `errors` array so operators can log provenance.\n */\nexport class ValidatedWorkerParseError extends OctoFlowError {\n  readonly errors: ParseError[];\n  constructor(message: string, errors: ParseError[]) {\n    super('VALIDATED_WORKER_PARSE_ERROR', message, {\n      errorCount: errors.length,\n    });\n    this.name = 'ValidatedWorkerParseError';\n    this.errors = errors;\n  }\n}\n\nregisterErrorClass(\n  'VALIDATED_WORKER_PARSE_ERROR',\n  (payload) => new ValidatedWorkerParseError(payload.message, [])\n);\n\nexport function createValidatedWorker<S extends ResponseSchema>(\n  opts: ValidatedWorkerOptions<S>\n): ValidatedWorker<S> {\n  const retries = opts.retries ?? 0;\n  const mode: ParseErrorMode = opts.onParseError ?? 'return-partial';\n\n  return {\n    async ask(prompt: string): Promise<ParseResult<InferSchema<S>>> {\n      let lastResult: ParseResult<InferSchema<S>> | undefined;\n      let currentPrompt = prompt;\n      for (let attempt = 0; attempt <= retries; attempt++) {\n        const text = await opts.ask(currentPrompt);\n        const parsed = parseResponse(text, opts.schema);\n        if (parsed.ok) return parsed;\n        lastResult = parsed;\n        if (attempt < retries) {\n          currentPrompt = buildRetryPrompt(prompt, opts.schema, parsed.errors);\n        }\n      }\n      if (mode === 'throw') {\n        throw new ValidatedWorkerParseError(\n          `validatedWorker: response did not match schema after ${retries + 1} attempt(s)`,\n          lastResult?.ok === false ? lastResult.errors : []\n        );\n      }\n      return lastResult ?? { ok: false, errors: [] };\n    },\n  };\n}\n\n/**\n * Embed a summarized schema-drift hint in the retry prompt. We\n * intentionally include only the field paths + error codes (not the full\n * errors array) to avoid overwhelming the LLM's context, per RFC \u00A710\n * open-question 2.\n */\nfunction buildRetryPrompt<S extends ResponseSchema>(\n  original: string,\n  schema: S,\n  errors: ParseError[]\n): string {\n  const summary = errors.map((e) => `  \u2022 ${e.path}: ${e.code}`).join('\\n');\n  return [\n    original,\n    '',\n    'Your last response did not match the expected schema:',\n    summary,\n    '',\n    describeSchemaForLLM(schema),\n  ].join('\\n');\n}\n"],
+  "mappings": "AAYA,SAAS,eAAe,0BAA0B;AAClD,SAAS,4BAA4B;AACrC,SAAS,qBAAqB;AAyCvB,MAAM,kCAAkC,cAAc;AAAA,EAClD;AAAA,EACT,YAAY,SAAiB,QAAsB;AACjD,UAAM,gCAAgC,SAAS;AAAA,MAC7C,YAAY,OAAO;AAAA,IACrB,CAAC;AACD,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;AAEA;AAAA,EACE;AAAA,EACA,CAAC,YAAY,IAAI,0BAA0B,QAAQ,SAAS,CAAC,CAAC;AAChE;AAEO,SAAS,sBACd,MACoB;AACpB,QAAM,UAAU,KAAK,WAAW;AAChC,QAAM,OAAuB,KAAK,gBAAgB;AAElD,SAAO;AAAA,IACL,MAAM,IAAI,QAAsD;AAC9D,UAAI;AACJ,UAAI,gBAAgB;AACpB,eAAS,UAAU,GAAG,WAAW,SAAS,WAAW;AACnD,cAAM,OAAO,MAAM,KAAK,IAAI,aAAa;AACzC,cAAM,SAAS,cAAc,MAAM,KAAK,MAAM;AAC9C,YAAI,OAAO,GAAI,QAAO;AACtB,qBAAa;AACb,YAAI,UAAU,SAAS;AACrB,0BAAgB,iBAAiB,QAAQ,KAAK,QAAQ,OAAO,MAAM;AAAA,QACrE;AAAA,MACF;AACA,UAAI,SAAS,SAAS;AACpB,cAAM,IAAI;AAAA,UACR,wDAAwD,UAAU,CAAC;AAAA,UACnE,YAAY,OAAO,QAAQ,WAAW,SAAS,CAAC;AAAA,QAClD;AAAA,MACF;AACA,aAAO,cAAc,EAAE,IAAI,OAAO,QAAQ,CAAC,EAAE;AAAA,IAC/C;AAAA,EACF;AACF;AAQA,SAAS,iBACP,UACA,QACA,QACQ;AACR,QAAM,UAAU,OAAO,IAAI,CAAC,MAAM,YAAO,EAAE,IAAI,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,IAAI;AACvE,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,qBAAqB,MAAM;AAAA,EAC7B,EAAE,KAAK,IAAI;AACb;",
+  "names": []
+}

package/dist/plugins/define.d.ts

@@ -0,0 +1,24 @@
+import type { BridgePlugin } from '../runtime/bridge/plugins.js';
+export interface PluginManifest {
+    name: string;
+    version?: string;
+    description?: string;
+    tags?: string[];
+    homepage?: string;
+    license?: string;
+    octoFlowVersion?: string;
+}
+/**
+ * Define and validate a native octoflow plugin.
+ *
+ * @example
+ * const plugin = createPlugin({
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   actions: [myAction],
+ *   async setup(ctx) { ctx.registerAction(myAction); },
+ * });
+ * await bridge.use(plugin);
+ */
+export declare function createPlugin(definition: PluginManifest & Omit<BridgePlugin, 'name' | 'version'>): BridgePlugin & PluginManifest;
+//# sourceMappingURL=define.d.ts.map

package/dist/plugins/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/plugins/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC,GAClE,YAAY,GAAG,cAAc,CAqD/B"}

package/dist/plugins/define.js

@@ -0,0 +1,62 @@
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/;
+const VALID_NAME_RE = /^(@[a-z0-9-]+\/)?[a-z0-9][a-z0-9-]*$/;
+function createPlugin(definition) {
+  const {
+    name,
+    version,
+    description,
+    tags,
+    homepage,
+    license,
+    octoFlowVersion,
+    ...rest
+  } = definition;
+  if (!name || !VALID_NAME_RE.test(name)) {
+    throw new Error(
+      `[octoflow] Invalid plugin name: "${name}". plugin name must be lowercase alphanumeric with hyphens (e.g. "my-plugin" or "@scope/my-plugin").`
+    );
+  }
+  if (version !== void 0 && !SEMVER_RE.test(version)) {
+    throw new Error(
+      `[octoflow] Invalid plugin version: "${version}". Must be valid semver (e.g. "1.0.0").`
+    );
+  }
+  const actionNames = (rest.actions ?? []).map((a) => a.name);
+  const duplicateActions = findDuplicates(actionNames);
+  if (duplicateActions.length > 0) {
+    throw new Error(
+      `[octoflow] Plugin "${name}" has duplicate action names: ${duplicateActions.join(", ")}.`
+    );
+  }
+  const skillNames = (rest.skills ?? []).map((s) => s.name);
+  const duplicateSkills = findDuplicates(skillNames);
+  if (duplicateSkills.length > 0) {
+    throw new Error(
+      `[octoflow] Plugin "${name}" has duplicate skill names: ${duplicateSkills.join(", ")}.`
+    );
+  }
+  const plugin = {
+    ...rest,
+    name,
+    version,
+    description,
+    tags,
+    homepage,
+    license,
+    octoFlowVersion
+  };
+  return plugin;
+}
+function findDuplicates(names) {
+  const seen = /* @__PURE__ */ new Set();
+  const dupes = /* @__PURE__ */ new Set();
+  for (const n of names) {
+    if (seen.has(n)) dupes.add(n);
+    else seen.add(n);
+  }
+  return [...dupes];
+}
+export {
+  createPlugin
+};
+//# sourceMappingURL=define.js.map

package/dist/plugins/define.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/plugins/define.ts"],
+  "sourcesContent": ["import type { BridgePlugin } from '../runtime/bridge/plugins.js';\n\nexport interface PluginManifest {\n  name: string;\n  version?: string;\n  description?: string;\n  tags?: string[];\n  homepage?: string;\n  license?: string;\n  octoFlowVersion?: string;\n}\n\nconst SEMVER_RE = /^\\d+\\.\\d+\\.\\d+(-[\\w.]+)?(\\+[\\w.]+)?$/;\nconst VALID_NAME_RE = /^(@[a-z0-9-]+\\/)?[a-z0-9][a-z0-9-]*$/;\n\n/**\n * Define and validate a native octoflow plugin.\n *\n * @example\n * const plugin = createPlugin({\n *   name: 'my-plugin',\n *   version: '1.0.0',\n *   actions: [myAction],\n *   async setup(ctx) { ctx.registerAction(myAction); },\n * });\n * await bridge.use(plugin);\n */\nexport function createPlugin(\n  definition: PluginManifest & Omit<BridgePlugin, 'name' | 'version'>\n): BridgePlugin & PluginManifest {\n  const {\n    name,\n    version,\n    description,\n    tags,\n    homepage,\n    license,\n    octoFlowVersion,\n    ...rest\n  } = definition;\n\n  if (!name || !VALID_NAME_RE.test(name)) {\n    throw new Error(\n      `[octoflow] Invalid plugin name: \"${name}\". ` +\n        'plugin name must be lowercase alphanumeric with hyphens (e.g. \"my-plugin\" or \"@scope/my-plugin\").'\n    );\n  }\n\n  if (version !== undefined && !SEMVER_RE.test(version)) {\n    throw new Error(\n      `[octoflow] Invalid plugin version: \"${version}\". Must be valid semver (e.g. \"1.0.0\").`\n    );\n  }\n\n  const actionNames = (rest.actions ?? []).map((a) => a.name);\n  const duplicateActions = findDuplicates(actionNames);\n  if (duplicateActions.length > 0) {\n    throw new Error(\n      `[octoflow] Plugin \"${name}\" has duplicate action names: ${duplicateActions.join(', ')}.`\n    );\n  }\n\n  const skillNames = (rest.skills ?? []).map((s) => s.name);\n  const duplicateSkills = findDuplicates(skillNames);\n  if (duplicateSkills.length > 0) {\n    throw new Error(\n      `[octoflow] Plugin \"${name}\" has duplicate skill names: ${duplicateSkills.join(', ')}.`\n    );\n  }\n\n  const plugin: BridgePlugin & PluginManifest = {\n    ...rest,\n    name,\n    version,\n    description,\n    tags,\n    homepage,\n    license,\n    octoFlowVersion,\n  };\n\n  return plugin;\n}\n\nfunction findDuplicates(names: string[]): string[] {\n  const seen = new Set<string>();\n  const dupes = new Set<string>();\n  for (const n of names) {\n    if (seen.has(n)) dupes.add(n);\n    else seen.add(n);\n  }\n  return [...dupes];\n}\n"],
+  "mappings": "AAYA,MAAM,YAAY;AAClB,MAAM,gBAAgB;AAcf,SAAS,aACd,YAC+B;AAC/B,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,IAAI;AAEJ,MAAI,CAAC,QAAQ,CAAC,cAAc,KAAK,IAAI,GAAG;AACtC,UAAM,IAAI;AAAA,MACR,oCAAoC,IAAI;AAAA,IAE1C;AAAA,EACF;AAEA,MAAI,YAAY,UAAa,CAAC,UAAU,KAAK,OAAO,GAAG;AACrD,UAAM,IAAI;AAAA,MACR,uCAAuC,OAAO;AAAA,IAChD;AAAA,EACF;AAEA,QAAM,eAAe,KAAK,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI;AAC1D,QAAM,mBAAmB,eAAe,WAAW;AACnD,MAAI,iBAAiB,SAAS,GAAG;AAC/B,UAAM,IAAI;AAAA,MACR,sBAAsB,IAAI,iCAAiC,iBAAiB,KAAK,IAAI,CAAC;AAAA,IACxF;AAAA,EACF;AAEA,QAAM,cAAc,KAAK,UAAU,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI;AACxD,QAAM,kBAAkB,eAAe,UAAU;AACjD,MAAI,gBAAgB,SAAS,GAAG;AAC9B,UAAM,IAAI;AAAA,MACR,sBAAsB,IAAI,gCAAgC,gBAAgB,KAAK,IAAI,CAAC;AAAA,IACtF;AAAA,EACF;AAEA,QAAM,SAAwC;AAAA,IAC5C,GAAG;AAAA,IACH;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,eAAe,OAA2B;AACjD,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAQ,oBAAI,IAAY;AAC9B,aAAW,KAAK,OAAO;AACrB,QAAI,KAAK,IAAI,CAAC,EAAG,OAAM,IAAI,CAAC;AAAA,QACvB,MAAK,IAAI,CAAC;AAAA,EACjB;AACA,SAAO,CAAC,GAAG,KAAK;AAClB;",
+  "names": []
+}

package/dist/plugins/test-context.d.ts

@@ -0,0 +1,29 @@
+import type { BridgeSendMessageParams } from '../domain/bridge-api.js';
+import type { Task } from '../domain/core-task.js';
+import type { BridgeEventMap } from '../runtime/bridge/events.js';
+import type { PluginContext } from '../runtime/bridge/plugins.js';
+export interface PluginTestContext extends PluginContext {
+    readonly registeredActions: string[];
+    readonly registeredSkills: string[];
+    readonly sentMessages: BridgeSendMessageParams[];
+    readonly tasks: Task[];
+    readonly warnings: string[];
+    setTask(task: Task): void;
+    simulateEvent<K extends keyof BridgeEventMap>(event: K, data: BridgeEventMap[K]): Promise<void>;
+}
+export interface CreatePluginTestContextOptions {
+    /** Default context id for tasks produced by sendMessage(). */
+    contextId?: string;
+    /** Seed tasks available through getTask() and listTasks(). */
+    tasks?: readonly Task[];
+}
+/**
+ * Creates an in-memory {@link PluginContext} for unit-testing plugins.
+ *
+ * @example
+ * const ctx = createPluginTestContext({ tasks: [existingTask] });
+ * await plugin.setup!(ctx);
+ * expect(ctx.registeredActions).toContain('my-action');
+ */
+export declare function createPluginTestContext(options?: CreatePluginTestContextOptions): PluginTestContext;
+//# sourceMappingURL=test-context.d.ts.map