octoflow-core 1.0.0

package/dist/domain/errors/agent.js

@@ -0,0 +1,81 @@
+import {
+  ctxNumber,
+  ctxString,
+  OctoFlowError,
+  registerErrorClass
+} from "./base.js";
+class AgentRunError extends OctoFlowError {
+  text;
+  exitCode;
+  backendName;
+  constructor(text, exitCode, backendName) {
+    super(
+      "AGENT_RUN_ERROR",
+      `[${backendName}] run failed (exit ${exitCode}): ${text.slice(0, 200)}`,
+      { text, exitCode, backendName }
+    );
+    this.name = "AgentRunError";
+    this.text = text;
+    this.exitCode = exitCode;
+    this.backendName = backendName;
+  }
+}
+registerErrorClass(
+  "AGENT_RUN_ERROR",
+  (p) => new AgentRunError(
+    ctxString(p.context, "text"),
+    ctxNumber(p.context, "exitCode"),
+    ctxString(p.context, "backendName")
+  )
+);
+class AgentTimeoutError extends OctoFlowError {
+  timeoutMs;
+  constructor(timeoutMs) {
+    super("AGENT_TIMEOUT", `CLI process timed out after ${timeoutMs}ms`, {
+      timeoutMs
+    });
+    this.name = "AgentTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+registerErrorClass(
+  "AGENT_TIMEOUT",
+  (p) => new AgentTimeoutError(ctxNumber(p.context, "timeoutMs"))
+);
+class UnsafeCommandError extends OctoFlowError {
+  command;
+  reason;
+  constructor(command, reason) {
+    super("UNSAFE_COMMAND", `Blocked unsafe command "${command}": ${reason}`, {
+      command,
+      reason
+    });
+    this.name = "UnsafeCommandError";
+    this.command = command;
+    this.reason = reason;
+  }
+}
+registerErrorClass(
+  "UNSAFE_COMMAND",
+  (p) => new UnsafeCommandError(
+    ctxString(p.context, "command"),
+    ctxString(p.context, "reason")
+  )
+);
+class SshConnectionError extends OctoFlowError {
+  constructor(message) {
+    super("SSH_CONNECTION_ERROR", message);
+    this.name = "SshConnectionError";
+  }
+}
+registerErrorClass(
+  "SSH_CONNECTION_ERROR",
+  (p) => new SshConnectionError(p.message)
+);
+export {
+  AgentRunError,
+  AgentTimeoutError,
+  SshConnectionError,
+  UnsafeCommandError
+};
+//# sourceMappingURL=agent.js.map

package/dist/domain/errors/agent.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/domain/errors/agent.ts"],
+  "sourcesContent": ["import {\n  ctxNumber,\n  ctxString,\n  OctoFlowError,\n  registerErrorClass,\n} from './base.js';\n\n/** Thrown when the agent returns an error result (is_error: true). */\nexport class AgentRunError extends OctoFlowError {\n  readonly text: string;\n  readonly exitCode: number;\n  readonly backendName: string;\n\n  constructor(text: string, exitCode: number, backendName: string) {\n    super(\n      'AGENT_RUN_ERROR',\n      `[${backendName}] run failed (exit ${exitCode}): ${text.slice(0, 200)}`,\n      { text, exitCode, backendName }\n    );\n    this.name = 'AgentRunError';\n    this.text = text;\n    this.exitCode = exitCode;\n    this.backendName = backendName;\n  }\n}\nregisterErrorClass(\n  'AGENT_RUN_ERROR',\n  (p) =>\n    new AgentRunError(\n      ctxString(p.context, 'text'),\n      ctxNumber(p.context, 'exitCode'),\n      ctxString(p.context, 'backendName')\n    )\n);\n\n/** Thrown when the CLI process exceeds the configured timeoutMs. */\nexport class AgentTimeoutError extends OctoFlowError {\n  readonly timeoutMs: number;\n\n  constructor(timeoutMs: number) {\n    super('AGENT_TIMEOUT', `CLI process timed out after ${timeoutMs}ms`, {\n      timeoutMs,\n    });\n    this.name = 'AgentTimeoutError';\n    this.timeoutMs = timeoutMs;\n  }\n}\nregisterErrorClass(\n  'AGENT_TIMEOUT',\n  (p) => new AgentTimeoutError(ctxNumber(p.context, 'timeoutMs'))\n);\n\n/** Thrown when a direct host command is blocked by the bridge safety policy. */\nexport class UnsafeCommandError extends OctoFlowError {\n  readonly command: string;\n  readonly reason: string;\n\n  constructor(command: string, reason: string) {\n    super('UNSAFE_COMMAND', `Blocked unsafe command \"${command}\": ${reason}`, {\n      command,\n      reason,\n    });\n    this.name = 'UnsafeCommandError';\n    this.command = command;\n    this.reason = reason;\n  }\n}\nregisterErrorClass(\n  'UNSAFE_COMMAND',\n  (p) =>\n    new UnsafeCommandError(\n      ctxString(p.context, 'command'),\n      ctxString(p.context, 'reason')\n    )\n);\n\n/** Thrown when an SSH connection or remote exec channel fails. */\nexport class SshConnectionError extends OctoFlowError {\n  constructor(message: string) {\n    super('SSH_CONNECTION_ERROR', message);\n    this.name = 'SshConnectionError';\n  }\n}\nregisterErrorClass(\n  'SSH_CONNECTION_ERROR',\n  (p) => new SshConnectionError(p.message)\n);\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGA,MAAM,sBAAsB,cAAc;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAAc,UAAkB,aAAqB;AAC/D;AAAA,MACE;AAAA,MACA,IAAI,WAAW,sBAAsB,QAAQ,MAAM,KAAK,MAAM,GAAG,GAAG,CAAC;AAAA,MACrE,EAAE,MAAM,UAAU,YAAY;AAAA,IAChC;AACA,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAChB,SAAK,cAAc;AAAA,EACrB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,MAAM;AAAA,IAC3B,UAAU,EAAE,SAAS,UAAU;AAAA,IAC/B,UAAU,EAAE,SAAS,aAAa;AAAA,EACpC;AACJ;AAGO,MAAM,0BAA0B,cAAc;AAAA,EAC1C;AAAA,EAET,YAAY,WAAmB;AAC7B,UAAM,iBAAiB,+BAA+B,SAAS,MAAM;AAAA,MACnE;AAAA,IACF,CAAC;AACD,SAAK,OAAO;AACZ,SAAK,YAAY;AAAA,EACnB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MAAM,IAAI,kBAAkB,UAAU,EAAE,SAAS,WAAW,CAAC;AAChE;AAGO,MAAM,2BAA2B,cAAc;AAAA,EAC3C;AAAA,EACA;AAAA,EAET,YAAY,SAAiB,QAAgB;AAC3C,UAAM,kBAAkB,2BAA2B,OAAO,MAAM,MAAM,IAAI;AAAA,MACxE;AAAA,MACA;AAAA,IACF,CAAC;AACD,SAAK,OAAO;AACZ,SAAK,UAAU;AACf,SAAK,SAAS;AAAA,EAChB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,SAAS;AAAA,IAC9B,UAAU,EAAE,SAAS,QAAQ;AAAA,EAC/B;AACJ;AAGO,MAAM,2BAA2B,cAAc;AAAA,EACpD,YAAY,SAAiB;AAC3B,UAAM,wBAAwB,OAAO;AACrC,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MAAM,IAAI,mBAAmB,EAAE,OAAO;AACzC;",
+  "names": []
+}

package/dist/domain/errors/api.d.ts

@@ -0,0 +1,22 @@
+import { OctoFlowError } from './base.js';
+/** Thrown when an API key is missing or invalid. */
+export declare class ApiKeyError extends OctoFlowError {
+    readonly provider: string;
+    constructor(provider: string, message?: string);
+}
+/**
+ * Thrown when an upstream API returns a non-2xx HTTP response.
+ * Callers can inspect `status` to decide retry behaviour (e.g. 429 → backoff, 5xx → retry).
+ */
+export declare class ApiHttpError extends OctoFlowError {
+    readonly provider: string;
+    readonly status: number;
+    readonly body: string;
+    constructor(provider: string, status: number, body: string);
+}
+/** Thrown when an API response stream is unreadable or yields a protocol error. */
+export declare class ApiStreamError extends OctoFlowError {
+    readonly provider: string;
+    constructor(provider: string, message: string);
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/domain/errors/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EAEd,MAAM,WAAW,CAAC;AAEnB,oDAAoD;AACpD,qBAAa,WAAY,SAAQ,aAAa;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAU/C;AAUD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,aAAa;IAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAW3D;AAWD,mFAAmF;AACnF,qBAAa,cAAe,SAAQ,aAAa;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAQ9C"}

package/dist/domain/errors/api.js

@@ -0,0 +1,73 @@
+import {
+  ctxNumber,
+  ctxString,
+  OctoFlowError,
+  registerErrorClass
+} from "./base.js";
+class ApiKeyError extends OctoFlowError {
+  provider;
+  constructor(provider, message) {
+    super(
+      "API_KEY_ERROR",
+      message ?? `API key for "${provider}" is missing or invalid. Set the corresponding environment variable.`,
+      { provider, ...message ? { messageOverride: message } : {} }
+    );
+    this.name = "ApiKeyError";
+    this.provider = provider;
+  }
+}
+registerErrorClass(
+  "API_KEY_ERROR",
+  (p) => new ApiKeyError(
+    ctxString(p.context, "provider"),
+    ctxString(p.context, "messageOverride") || void 0
+  )
+);
+class ApiHttpError extends OctoFlowError {
+  provider;
+  status;
+  body;
+  constructor(provider, status, body) {
+    super(
+      "API_HTTP_ERROR",
+      `${provider} API returned HTTP ${status}: ${body.slice(0, 300)}`,
+      { provider, status, body }
+    );
+    this.name = "ApiHttpError";
+    this.provider = provider;
+    this.status = status;
+    this.body = body;
+  }
+}
+registerErrorClass(
+  "API_HTTP_ERROR",
+  (p) => new ApiHttpError(
+    ctxString(p.context, "provider"),
+    ctxNumber(p.context, "status"),
+    ctxString(p.context, "body")
+  )
+);
+class ApiStreamError extends OctoFlowError {
+  provider;
+  constructor(provider, message) {
+    super("API_STREAM_ERROR", `${provider} stream error: ${message}`, {
+      provider,
+      innerMessage: message
+    });
+    this.name = "ApiStreamError";
+    this.provider = provider;
+  }
+}
+registerErrorClass(
+  "API_STREAM_ERROR",
+  (p) => new ApiStreamError(
+    ctxString(p.context, "provider"),
+    ctxString(p.context, "innerMessage") || p.message
+  )
+);
+export {
+  ApiHttpError,
+  ApiKeyError,
+  ApiStreamError
+};
+//# sourceMappingURL=api.js.map

package/dist/domain/errors/api.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/domain/errors/api.ts"],
+  "sourcesContent": ["import {\n  ctxNumber,\n  ctxString,\n  OctoFlowError,\n  registerErrorClass,\n} from './base.js';\n\n/** Thrown when an API key is missing or invalid. */\nexport class ApiKeyError extends OctoFlowError {\n  readonly provider: string;\n\n  constructor(provider: string, message?: string) {\n    super(\n      'API_KEY_ERROR',\n      message ??\n        `API key for \"${provider}\" is missing or invalid. Set the corresponding environment variable.`,\n      { provider, ...(message ? { messageOverride: message } : {}) }\n    );\n    this.name = 'ApiKeyError';\n    this.provider = provider;\n  }\n}\nregisterErrorClass(\n  'API_KEY_ERROR',\n  (p) =>\n    new ApiKeyError(\n      ctxString(p.context, 'provider'),\n      ctxString(p.context, 'messageOverride') || undefined\n    )\n);\n\n/**\n * Thrown when an upstream API returns a non-2xx HTTP response.\n * Callers can inspect `status` to decide retry behaviour (e.g. 429 \u2192 backoff, 5xx \u2192 retry).\n */\nexport class ApiHttpError extends OctoFlowError {\n  readonly provider: string;\n  readonly status: number;\n  readonly body: string;\n\n  constructor(provider: string, status: number, body: string) {\n    super(\n      'API_HTTP_ERROR',\n      `${provider} API returned HTTP ${status}: ${body.slice(0, 300)}`,\n      { provider, status, body }\n    );\n    this.name = 'ApiHttpError';\n    this.provider = provider;\n    this.status = status;\n    this.body = body;\n  }\n}\nregisterErrorClass(\n  'API_HTTP_ERROR',\n  (p) =>\n    new ApiHttpError(\n      ctxString(p.context, 'provider'),\n      ctxNumber(p.context, 'status'),\n      ctxString(p.context, 'body')\n    )\n);\n\n/** Thrown when an API response stream is unreadable or yields a protocol error. */\nexport class ApiStreamError extends OctoFlowError {\n  readonly provider: string;\n\n  constructor(provider: string, message: string) {\n    super('API_STREAM_ERROR', `${provider} stream error: ${message}`, {\n      provider,\n      innerMessage: message,\n    });\n    this.name = 'ApiStreamError';\n    this.provider = provider;\n  }\n}\nregisterErrorClass(\n  'API_STREAM_ERROR',\n  (p) =>\n    new ApiStreamError(\n      ctxString(p.context, 'provider'),\n      ctxString(p.context, 'innerMessage') || p.message\n    )\n);\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGA,MAAM,oBAAoB,cAAc;AAAA,EACpC;AAAA,EAET,YAAY,UAAkB,SAAkB;AAC9C;AAAA,MACE;AAAA,MACA,WACE,gBAAgB,QAAQ;AAAA,MAC1B,EAAE,UAAU,GAAI,UAAU,EAAE,iBAAiB,QAAQ,IAAI,CAAC,EAAG;AAAA,IAC/D;AACA,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,UAAU;AAAA,IAC/B,UAAU,EAAE,SAAS,iBAAiB,KAAK;AAAA,EAC7C;AACJ;AAMO,MAAM,qBAAqB,cAAc;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,UAAkB,QAAgB,MAAc;AAC1D;AAAA,MACE;AAAA,MACA,GAAG,QAAQ,sBAAsB,MAAM,KAAK,KAAK,MAAM,GAAG,GAAG,CAAC;AAAA,MAC9D,EAAE,UAAU,QAAQ,KAAK;AAAA,IAC3B;AACA,SAAK,OAAO;AACZ,SAAK,WAAW;AAChB,SAAK,SAAS;AACd,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,UAAU;AAAA,IAC/B,UAAU,EAAE,SAAS,QAAQ;AAAA,IAC7B,UAAU,EAAE,SAAS,MAAM;AAAA,EAC7B;AACJ;AAGO,MAAM,uBAAuB,cAAc;AAAA,EACvC;AAAA,EAET,YAAY,UAAkB,SAAiB;AAC7C,UAAM,oBAAoB,GAAG,QAAQ,kBAAkB,OAAO,IAAI;AAAA,MAChE;AAAA,MACA,cAAc;AAAA,IAChB,CAAC;AACD,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,UAAU;AAAA,IAC/B,UAAU,EAAE,SAAS,cAAc,KAAK,EAAE;AAAA,EAC5C;AACJ;",
+  "names": []
+}

package/dist/domain/errors/approval.d.ts

@@ -0,0 +1,18 @@
+import { OctoFlowError } from './base.js';
+/** Thrown when an approval is not found in the approval store. */
+export declare class ApprovalNotFoundError extends OctoFlowError {
+    constructor(approvalId: string);
+}
+/** Thrown when an approval state transition is invalid. */
+export declare class ApprovalStateError extends OctoFlowError {
+    constructor(approvalId: string, currentStatus: string, targetStatus: string);
+}
+/**
+ * Thrown when an approval `update` is rejected because the row's status
+ * changed between the read and the write — i.e., another resolver won the
+ * race. Retry by re-reading the approval.
+ */
+export declare class ApprovalConcurrencyError extends OctoFlowError {
+    constructor(approvalId: string, expectedStatus: string, actualStatus: string);
+}
+//# sourceMappingURL=approval.d.ts.map

package/dist/domain/errors/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/approval.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,aAAa,EAAsB,MAAM,WAAW,CAAC;AAEzE,kEAAkE;AAClE,qBAAa,qBAAsB,SAAQ,aAAa;gBAC1C,UAAU,EAAE,MAAM;CAM/B;AAMD,2DAA2D;AAC3D,qBAAa,kBAAmB,SAAQ,aAAa;gBACvC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAQ5E;AAWD;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;gBAEvD,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM;CASvB"}

package/dist/domain/errors/approval.js

@@ -0,0 +1,55 @@
+import { ctxString, OctoFlowError, registerErrorClass } from "./base.js";
+class ApprovalNotFoundError extends OctoFlowError {
+  constructor(approvalId) {
+    super("APPROVAL_NOT_FOUND", `Approval not found: "${approvalId}"`, {
+      approvalId
+    });
+    this.name = "ApprovalNotFoundError";
+  }
+}
+registerErrorClass(
+  "APPROVAL_NOT_FOUND",
+  (p) => new ApprovalNotFoundError(ctxString(p.context, "approvalId"))
+);
+class ApprovalStateError extends OctoFlowError {
+  constructor(approvalId, currentStatus, targetStatus) {
+    super(
+      "APPROVAL_STATE_ERROR",
+      `Cannot transition approval "${approvalId}" from "${currentStatus}" to "${targetStatus}".`,
+      { approvalId, currentStatus, targetStatus }
+    );
+    this.name = "ApprovalStateError";
+  }
+}
+registerErrorClass(
+  "APPROVAL_STATE_ERROR",
+  (p) => new ApprovalStateError(
+    ctxString(p.context, "approvalId"),
+    ctxString(p.context, "currentStatus"),
+    ctxString(p.context, "targetStatus")
+  )
+);
+class ApprovalConcurrencyError extends OctoFlowError {
+  constructor(approvalId, expectedStatus, actualStatus) {
+    super(
+      "APPROVAL_CONCURRENCY_ERROR",
+      `Approval "${approvalId}" changed underneath us \u2014 expected status "${expectedStatus}", found "${actualStatus}".`,
+      { approvalId, expectedStatus, actualStatus }
+    );
+    this.name = "ApprovalConcurrencyError";
+  }
+}
+registerErrorClass(
+  "APPROVAL_CONCURRENCY_ERROR",
+  (p) => new ApprovalConcurrencyError(
+    ctxString(p.context, "approvalId"),
+    ctxString(p.context, "expectedStatus"),
+    ctxString(p.context, "actualStatus")
+  )
+);
+export {
+  ApprovalConcurrencyError,
+  ApprovalNotFoundError,
+  ApprovalStateError
+};
+//# sourceMappingURL=approval.js.map

package/dist/domain/errors/approval.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/domain/errors/approval.ts"],
+  "sourcesContent": ["import { ctxString, OctoFlowError, registerErrorClass } from './base.js';\n\n/** Thrown when an approval is not found in the approval store. */\nexport class ApprovalNotFoundError extends OctoFlowError {\n  constructor(approvalId: string) {\n    super('APPROVAL_NOT_FOUND', `Approval not found: \"${approvalId}\"`, {\n      approvalId,\n    });\n    this.name = 'ApprovalNotFoundError';\n  }\n}\nregisterErrorClass(\n  'APPROVAL_NOT_FOUND',\n  (p) => new ApprovalNotFoundError(ctxString(p.context, 'approvalId'))\n);\n\n/** Thrown when an approval state transition is invalid. */\nexport class ApprovalStateError extends OctoFlowError {\n  constructor(approvalId: string, currentStatus: string, targetStatus: string) {\n    super(\n      'APPROVAL_STATE_ERROR',\n      `Cannot transition approval \"${approvalId}\" from \"${currentStatus}\" to \"${targetStatus}\".`,\n      { approvalId, currentStatus, targetStatus }\n    );\n    this.name = 'ApprovalStateError';\n  }\n}\nregisterErrorClass(\n  'APPROVAL_STATE_ERROR',\n  (p) =>\n    new ApprovalStateError(\n      ctxString(p.context, 'approvalId'),\n      ctxString(p.context, 'currentStatus'),\n      ctxString(p.context, 'targetStatus')\n    )\n);\n\n/**\n * Thrown when an approval `update` is rejected because the row's status\n * changed between the read and the write \u2014 i.e., another resolver won the\n * race. Retry by re-reading the approval.\n */\nexport class ApprovalConcurrencyError extends OctoFlowError {\n  constructor(\n    approvalId: string,\n    expectedStatus: string,\n    actualStatus: string\n  ) {\n    super(\n      'APPROVAL_CONCURRENCY_ERROR',\n      `Approval \"${approvalId}\" changed underneath us \u2014 expected status \"${expectedStatus}\", found \"${actualStatus}\".`,\n      { approvalId, expectedStatus, actualStatus }\n    );\n    this.name = 'ApprovalConcurrencyError';\n  }\n}\nregisterErrorClass(\n  'APPROVAL_CONCURRENCY_ERROR',\n  (p) =>\n    new ApprovalConcurrencyError(\n      ctxString(p.context, 'approvalId'),\n      ctxString(p.context, 'expectedStatus'),\n      ctxString(p.context, 'actualStatus')\n    )\n);\n"],
+  "mappings": "AAAA,SAAS,WAAW,eAAe,0BAA0B;AAGtD,MAAM,8BAA8B,cAAc;AAAA,EACvD,YAAY,YAAoB;AAC9B,UAAM,sBAAsB,wBAAwB,UAAU,KAAK;AAAA,MACjE;AAAA,IACF,CAAC;AACD,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MAAM,IAAI,sBAAsB,UAAU,EAAE,SAAS,YAAY,CAAC;AACrE;AAGO,MAAM,2BAA2B,cAAc;AAAA,EACpD,YAAY,YAAoB,eAAuB,cAAsB;AAC3E;AAAA,MACE;AAAA,MACA,+BAA+B,UAAU,WAAW,aAAa,SAAS,YAAY;AAAA,MACtF,EAAE,YAAY,eAAe,aAAa;AAAA,IAC5C;AACA,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,YAAY;AAAA,IACjC,UAAU,EAAE,SAAS,eAAe;AAAA,IACpC,UAAU,EAAE,SAAS,cAAc;AAAA,EACrC;AACJ;AAOO,MAAM,iCAAiC,cAAc;AAAA,EAC1D,YACE,YACA,gBACA,cACA;AACA;AAAA,MACE;AAAA,MACA,aAAa,UAAU,mDAA8C,cAAc,aAAa,YAAY;AAAA,MAC5G,EAAE,YAAY,gBAAgB,aAAa;AAAA,IAC7C;AACA,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,YAAY;AAAA,IACjC,UAAU,EAAE,SAAS,gBAAgB;AAAA,IACrC,UAAU,EAAE,SAAS,cAAc;AAAA,EACrC;AACJ;",
+  "names": []
+}

package/dist/domain/errors/backend.d.ts

@@ -0,0 +1,34 @@
+import { OctoFlowError } from './base.js';
+/** Thrown when the requested backend's CLI is not installed or API key is missing. */
+export declare class BackendNotAvailableError extends OctoFlowError {
+    readonly backendName: string;
+    constructor(backendName: string, reason?: string);
+}
+/**
+ * Thrown when no backend in the configured priority list is ready.
+ * `checked` lists all backends that were tried and their reasons.
+ */
+export declare class NoBackendAvailableError extends OctoFlowError {
+    readonly checked: {
+        backend: string;
+        reason: string;
+    }[];
+    constructor(checked: {
+        backend: string;
+        reason: string;
+    }[]);
+}
+/** Thrown when an explicit backend switch target is not available or not in the priority list. */
+export declare class BackendSwitchRejectedError extends OctoFlowError {
+    readonly targetBackend: string;
+    constructor(targetBackend: string, reason?: string);
+}
+/** Thrown when the maximum number of backend switches per context has been reached. */
+export declare class BackendSwitchLimitError extends OctoFlowError {
+    constructor(contextId: string, limit: number);
+}
+/** Thrown when a cross-family backend switch is blocked by policy. */
+export declare class BackendSwitchUnsupportedError extends OctoFlowError {
+    constructor(fromBackend: string, toBackend: string);
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/domain/errors/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,aAAa,EAEd,MAAM,WAAW,CAAC;AAEnB,sFAAsF;AACtF,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAYjD;AAUD;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,aAAa;IACxD,QAAQ,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;gBAE5C,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE;CAU3D;AASD,kGAAkG;AAClG,qBAAa,0BAA2B,SAAQ,aAAa;IAC3D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAYnD;AAUD,uFAAuF;AACvF,qBAAa,uBAAwB,SAAQ,aAAa;gBAC5C,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAQ7C;AAUD,sEAAsE;AACtE,qBAAa,6BAA8B,SAAQ,aAAa;gBAClD,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAQnD"}

package/dist/domain/errors/backend.js

@@ -0,0 +1,105 @@
+import {
+  ctxNumber,
+  ctxString,
+  OctoFlowError,
+  registerErrorClass
+} from "./base.js";
+class BackendNotAvailableError extends OctoFlowError {
+  backendName;
+  constructor(backendName, reason) {
+    super(
+      "BACKEND_NOT_AVAILABLE",
+      `Backend "${backendName}" is not available` + (reason ? `: ${reason}` : ". Check the CLI is installed or the API key is set."),
+      { backendName, ...reason ? { reason } : {} }
+    );
+    this.name = "BackendNotAvailableError";
+    this.backendName = backendName;
+  }
+}
+registerErrorClass(
+  "BACKEND_NOT_AVAILABLE",
+  (p) => new BackendNotAvailableError(
+    ctxString(p.context, "backendName"),
+    ctxString(p.context, "reason") || void 0
+  )
+);
+class NoBackendAvailableError extends OctoFlowError {
+  checked;
+  constructor(checked) {
+    const list = checked.map((c) => `  \u2022 ${c.backend}: ${c.reason}`).join("\n");
+    super(
+      "NO_BACKEND_AVAILABLE",
+      `No AI backend is available. Tried:
+${list}`,
+      { checked }
+    );
+    this.name = "NoBackendAvailableError";
+    this.checked = checked;
+  }
+}
+registerErrorClass("NO_BACKEND_AVAILABLE", (p) => {
+  const raw = p.context?.checked;
+  const checked = Array.isArray(raw) ? raw : [];
+  return new NoBackendAvailableError(checked);
+});
+class BackendSwitchRejectedError extends OctoFlowError {
+  targetBackend;
+  constructor(targetBackend, reason) {
+    super(
+      "BACKEND_SWITCH_REJECTED",
+      `Backend switch to "${targetBackend}" rejected` + (reason ? `: ${reason}` : ". Target is not available or not in the priority list."),
+      { targetBackend, ...reason ? { reason } : {} }
+    );
+    this.name = "BackendSwitchRejectedError";
+    this.targetBackend = targetBackend;
+  }
+}
+registerErrorClass(
+  "BACKEND_SWITCH_REJECTED",
+  (p) => new BackendSwitchRejectedError(
+    ctxString(p.context, "targetBackend"),
+    ctxString(p.context, "reason") || void 0
+  )
+);
+class BackendSwitchLimitError extends OctoFlowError {
+  constructor(contextId, limit) {
+    super(
+      "BACKEND_SWITCH_LIMIT",
+      `Context "${contextId}" has reached the maximum switch limit (${limit}).`,
+      { contextId, limit }
+    );
+    this.name = "BackendSwitchLimitError";
+  }
+}
+registerErrorClass(
+  "BACKEND_SWITCH_LIMIT",
+  (p) => new BackendSwitchLimitError(
+    ctxString(p.context, "contextId"),
+    ctxNumber(p.context, "limit")
+  )
+);
+class BackendSwitchUnsupportedError extends OctoFlowError {
+  constructor(fromBackend, toBackend) {
+    super(
+      "BACKEND_SWITCH_UNSUPPORTED",
+      `Cross-family switch from "${fromBackend}" to "${toBackend}" is not allowed by policy.`,
+      { fromBackend, toBackend }
+    );
+    this.name = "BackendSwitchUnsupportedError";
+  }
+}
+registerErrorClass(
+  "BACKEND_SWITCH_UNSUPPORTED",
+  (p) => new BackendSwitchUnsupportedError(
+    ctxString(p.context, "fromBackend"),
+    ctxString(p.context, "toBackend")
+  )
+);
+export {
+  BackendNotAvailableError,
+  BackendSwitchLimitError,
+  BackendSwitchRejectedError,
+  BackendSwitchUnsupportedError,
+  NoBackendAvailableError
+};
+//# sourceMappingURL=backend.js.map

package/dist/domain/errors/backend.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/domain/errors/backend.ts"],
+  "sourcesContent": ["import {\n  ctxNumber,\n  ctxString,\n  OctoFlowError,\n  registerErrorClass,\n} from './base.js';\n\n/** Thrown when the requested backend's CLI is not installed or API key is missing. */\nexport class BackendNotAvailableError extends OctoFlowError {\n  readonly backendName: string;\n\n  constructor(backendName: string, reason?: string) {\n    super(\n      'BACKEND_NOT_AVAILABLE',\n      `Backend \"${backendName}\" is not available` +\n        (reason\n          ? `: ${reason}`\n          : '. Check the CLI is installed or the API key is set.'),\n      { backendName, ...(reason ? { reason } : {}) }\n    );\n    this.name = 'BackendNotAvailableError';\n    this.backendName = backendName;\n  }\n}\nregisterErrorClass(\n  'BACKEND_NOT_AVAILABLE',\n  (p) =>\n    new BackendNotAvailableError(\n      ctxString(p.context, 'backendName'),\n      ctxString(p.context, 'reason') || undefined\n    )\n);\n\n/**\n * Thrown when no backend in the configured priority list is ready.\n * `checked` lists all backends that were tried and their reasons.\n */\nexport class NoBackendAvailableError extends OctoFlowError {\n  readonly checked: { backend: string; reason: string }[];\n\n  constructor(checked: { backend: string; reason: string }[]) {\n    const list = checked.map((c) => `  \u2022 ${c.backend}: ${c.reason}`).join('\\n');\n    super(\n      'NO_BACKEND_AVAILABLE',\n      `No AI backend is available. Tried:\\n${list}`,\n      { checked }\n    );\n    this.name = 'NoBackendAvailableError';\n    this.checked = checked;\n  }\n}\nregisterErrorClass('NO_BACKEND_AVAILABLE', (p) => {\n  const raw = p.context?.checked;\n  const checked = Array.isArray(raw)\n    ? (raw as { backend: string; reason: string }[])\n    : [];\n  return new NoBackendAvailableError(checked);\n});\n\n/** Thrown when an explicit backend switch target is not available or not in the priority list. */\nexport class BackendSwitchRejectedError extends OctoFlowError {\n  readonly targetBackend: string;\n\n  constructor(targetBackend: string, reason?: string) {\n    super(\n      'BACKEND_SWITCH_REJECTED',\n      `Backend switch to \"${targetBackend}\" rejected` +\n        (reason\n          ? `: ${reason}`\n          : '. Target is not available or not in the priority list.'),\n      { targetBackend, ...(reason ? { reason } : {}) }\n    );\n    this.name = 'BackendSwitchRejectedError';\n    this.targetBackend = targetBackend;\n  }\n}\nregisterErrorClass(\n  'BACKEND_SWITCH_REJECTED',\n  (p) =>\n    new BackendSwitchRejectedError(\n      ctxString(p.context, 'targetBackend'),\n      ctxString(p.context, 'reason') || undefined\n    )\n);\n\n/** Thrown when the maximum number of backend switches per context has been reached. */\nexport class BackendSwitchLimitError extends OctoFlowError {\n  constructor(contextId: string, limit: number) {\n    super(\n      'BACKEND_SWITCH_LIMIT',\n      `Context \"${contextId}\" has reached the maximum switch limit (${limit}).`,\n      { contextId, limit }\n    );\n    this.name = 'BackendSwitchLimitError';\n  }\n}\nregisterErrorClass(\n  'BACKEND_SWITCH_LIMIT',\n  (p) =>\n    new BackendSwitchLimitError(\n      ctxString(p.context, 'contextId'),\n      ctxNumber(p.context, 'limit')\n    )\n);\n\n/** Thrown when a cross-family backend switch is blocked by policy. */\nexport class BackendSwitchUnsupportedError extends OctoFlowError {\n  constructor(fromBackend: string, toBackend: string) {\n    super(\n      'BACKEND_SWITCH_UNSUPPORTED',\n      `Cross-family switch from \"${fromBackend}\" to \"${toBackend}\" is not allowed by policy.`,\n      { fromBackend, toBackend }\n    );\n    this.name = 'BackendSwitchUnsupportedError';\n  }\n}\nregisterErrorClass(\n  'BACKEND_SWITCH_UNSUPPORTED',\n  (p) =>\n    new BackendSwitchUnsupportedError(\n      ctxString(p.context, 'fromBackend'),\n      ctxString(p.context, 'toBackend')\n    )\n);\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAGA,MAAM,iCAAiC,cAAc;AAAA,EACjD;AAAA,EAET,YAAY,aAAqB,QAAiB;AAChD;AAAA,MACE;AAAA,MACA,YAAY,WAAW,wBACpB,SACG,KAAK,MAAM,KACX;AAAA,MACN,EAAE,aAAa,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC,EAAG;AAAA,IAC/C;AACA,SAAK,OAAO;AACZ,SAAK,cAAc;AAAA,EACrB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,aAAa;AAAA,IAClC,UAAU,EAAE,SAAS,QAAQ,KAAK;AAAA,EACpC;AACJ;AAMO,MAAM,gCAAgC,cAAc;AAAA,EAChD;AAAA,EAET,YAAY,SAAgD;AAC1D,UAAM,OAAO,QAAQ,IAAI,CAAC,MAAM,YAAO,EAAE,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,IAAI;AAC1E;AAAA,MACE;AAAA,MACA;AAAA,EAAuC,IAAI;AAAA,MAC3C,EAAE,QAAQ;AAAA,IACZ;AACA,SAAK,OAAO;AACZ,SAAK,UAAU;AAAA,EACjB;AACF;AACA,mBAAmB,wBAAwB,CAAC,MAAM;AAChD,QAAM,MAAM,EAAE,SAAS;AACvB,QAAM,UAAU,MAAM,QAAQ,GAAG,IAC5B,MACD,CAAC;AACL,SAAO,IAAI,wBAAwB,OAAO;AAC5C,CAAC;AAGM,MAAM,mCAAmC,cAAc;AAAA,EACnD;AAAA,EAET,YAAY,eAAuB,QAAiB;AAClD;AAAA,MACE;AAAA,MACA,sBAAsB,aAAa,gBAChC,SACG,KAAK,MAAM,KACX;AAAA,MACN,EAAE,eAAe,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC,EAAG;AAAA,IACjD;AACA,SAAK,OAAO;AACZ,SAAK,gBAAgB;AAAA,EACvB;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,eAAe;AAAA,IACpC,UAAU,EAAE,SAAS,QAAQ,KAAK;AAAA,EACpC;AACJ;AAGO,MAAM,gCAAgC,cAAc;AAAA,EACzD,YAAY,WAAmB,OAAe;AAC5C;AAAA,MACE;AAAA,MACA,YAAY,SAAS,2CAA2C,KAAK;AAAA,MACrE,EAAE,WAAW,MAAM;AAAA,IACrB;AACA,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,WAAW;AAAA,IAChC,UAAU,EAAE,SAAS,OAAO;AAAA,EAC9B;AACJ;AAGO,MAAM,sCAAsC,cAAc;AAAA,EAC/D,YAAY,aAAqB,WAAmB;AAClD;AAAA,MACE;AAAA,MACA,6BAA6B,WAAW,SAAS,SAAS;AAAA,MAC1D,EAAE,aAAa,UAAU;AAAA,IAC3B;AACA,SAAK,OAAO;AAAA,EACd;AACF;AACA;AAAA,EACE;AAAA,EACA,CAAC,MACC,IAAI;AAAA,IACF,UAAU,EAAE,SAAS,aAAa;AAAA,IAClC,UAAU,EAAE,SAAS,WAAW;AAAA,EAClC;AACJ;",
+  "names": []
+}

package/dist/domain/errors/base.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Structured payload emitted by {@link OctoFlowError.toJSON} and consumed
+ * by {@link deserializeError}. Crosses the A2A wire and the adapter transport.
+ */
+export interface SerializedError {
+    name: string;
+    code: string;
+    message: string;
+    context?: Readonly<Record<string, unknown>>;
+    cause?: SerializedCause;
+    /** Present only when the emitter opts in (off by default in production). */
+    stack?: string;
+}
+export interface SerializedCause {
+    name?: string;
+    message: string;
+    code?: string;
+}
+/**
+ * Factory that rebuilds a concrete subclass from a serialized payload.
+ * Registered via {@link registerErrorClass}.
+ */
+type ErrorFactory = (payload: SerializedError) => OctoFlowError;
+/** Subclasses call this once at module load to opt in to typed deserialization. */
+export declare function registerErrorClass(code: string, factory: ErrorFactory): void;
+/** Present for introspection/tests; returns a snapshot, not a live view. */
+export declare function registeredErrorCodes(): readonly string[];
+/**
+ * Toggle whether {@link OctoFlowError.toJSON} includes `.stack`. Off by
+ * default; the A2A server opts in when the config says it is safe (dev / debug
+ * builds) — avoids leaking internal paths to untrusted callers in production.
+ */
+export declare function setExposeStacks(value: boolean): void;
+/** Reads a string field from a serialized error's context bag, with a safe fallback. */
+export declare function ctxString(ctx: Readonly<Record<string, unknown>> | undefined, key: string, fallback?: string): string;
+/** Reads a number field from a serialized error's context bag, with a safe fallback. */
+export declare function ctxNumber(ctx: Readonly<Record<string, unknown>> | undefined, key: string, fallback?: number): number;
+/** Common base class for all octoflow errors. */
+export declare class OctoFlowError extends Error {
+    readonly code: string;
+    readonly context: Readonly<Record<string, unknown>>;
+    constructor(code: string, message: string, context?: Record<string, unknown>);
+    toJSON(): SerializedError;
+}
+/**
+ * Rebuild an {@link OctoFlowError} from a {@link SerializedError} payload.
+ * Falls back to the generic base class when the `code` is unknown (never
+ * throws — callers prefer a best-effort reconstruction over an exception).
+ */
+export declare function deserializeError(payload: SerializedError): OctoFlowError;
+export {};
+//# sourceMappingURL=base.d.ts.map

package/dist/domain/errors/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,KAAK,YAAY,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,aAAa,CAAC;AAIhE,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAE5E;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,IAAI,SAAS,MAAM,EAAE,CAExD;AAGD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAEpD;AAKD,wFAAwF;AACxF,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EAClD,GAAG,EAAE,MAAM,EACX,QAAQ,SAAK,GACZ,MAAM,CAGR;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,EAClD,GAAG,EAAE,MAAM,EACX,QAAQ,SAAI,GACX,MAAM,CAGR;AAoBD,iDAAiD;AACjD,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;gBAGlD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;IAavC,MAAM,IAAI,eAAe;CAY1B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,aAAa,CAQxE"}

package/dist/domain/errors/base.js

@@ -0,0 +1,81 @@
+const ERROR_CLASS_BY_CODE = /* @__PURE__ */ new Map();
+function registerErrorClass(code, factory) {
+  ERROR_CLASS_BY_CODE.set(code, factory);
+}
+function registeredErrorCodes() {
+  return Array.from(ERROR_CLASS_BY_CODE.keys());
+}
+let exposeStackConfig = false;
+function setExposeStacks(value) {
+  exposeStackConfig = value;
+}
+function shouldExposeStack() {
+  return exposeStackConfig;
+}
+function ctxString(ctx, key, fallback = "") {
+  const value = ctx?.[key];
+  return typeof value === "string" ? value : fallback;
+}
+function ctxNumber(ctx, key, fallback = 0) {
+  const value = ctx?.[key];
+  return typeof value === "number" ? value : fallback;
+}
+function serializeCause(cause) {
+  if (!cause) return void 0;
+  if (cause instanceof OctoFlowError) {
+    return { name: cause.name, message: cause.message, code: cause.code };
+  }
+  if (cause instanceof Error) {
+    return { name: cause.name, message: cause.message };
+  }
+  if (typeof cause === "string") {
+    return { message: cause };
+  }
+  try {
+    return { message: JSON.stringify(cause) };
+  } catch {
+    return { message: Object.prototype.toString.call(cause) };
+  }
+}
+class OctoFlowError extends Error {
+  code;
+  context;
+  constructor(code, message, context = {}) {
+    super(message);
+    this.name = "OctoFlowError";
+    this.code = code;
+    this.context = Object.freeze({ ...context });
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  toJSON() {
+    const payload = {
+      name: this.name,
+      code: this.code,
+      message: this.message
+    };
+    if (Object.keys(this.context).length > 0) payload.context = this.context;
+    const cause = serializeCause(this.cause);
+    if (cause) payload.cause = cause;
+    if (shouldExposeStack() && this.stack) payload.stack = this.stack;
+    return payload;
+  }
+}
+function deserializeError(payload) {
+  const factory = ERROR_CLASS_BY_CODE.get(payload.code);
+  const err = factory ? factory(payload) : new OctoFlowError(payload.code, payload.message, payload.context ?? {});
+  if (!factory) err.name = payload.name;
+  if (payload.stack) err.stack = payload.stack;
+  return err;
+}
+export {
+  OctoFlowError,
+  ctxNumber,
+  ctxString,
+  deserializeError,
+  registerErrorClass,
+  registeredErrorCodes,
+  setExposeStacks
+};
+//# sourceMappingURL=base.js.map

package/dist/domain/errors/base.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/domain/errors/base.ts"],
+  "sourcesContent": ["/**\n * Structured payload emitted by {@link OctoFlowError.toJSON} and consumed\n * by {@link deserializeError}. Crosses the A2A wire and the adapter transport.\n */\nexport interface SerializedError {\n  name: string;\n  code: string;\n  message: string;\n  context?: Readonly<Record<string, unknown>>;\n  cause?: SerializedCause;\n  /** Present only when the emitter opts in (off by default in production). */\n  stack?: string;\n}\n\nexport interface SerializedCause {\n  name?: string;\n  message: string;\n  code?: string;\n}\n\n/**\n * Factory that rebuilds a concrete subclass from a serialized payload.\n * Registered via {@link registerErrorClass}.\n */\ntype ErrorFactory = (payload: SerializedError) => OctoFlowError;\n\nconst ERROR_CLASS_BY_CODE = new Map<string, ErrorFactory>();\n\n/** Subclasses call this once at module load to opt in to typed deserialization. */\nexport function registerErrorClass(code: string, factory: ErrorFactory): void {\n  ERROR_CLASS_BY_CODE.set(code, factory);\n}\n\n/** Present for introspection/tests; returns a snapshot, not a live view. */\nexport function registeredErrorCodes(): readonly string[] {\n  return Array.from(ERROR_CLASS_BY_CODE.keys());\n}\n\nlet exposeStackConfig = false;\n/**\n * Toggle whether {@link OctoFlowError.toJSON} includes `.stack`. Off by\n * default; the A2A server opts in when the config says it is safe (dev / debug\n * builds) \u2014 avoids leaking internal paths to untrusted callers in production.\n */\nexport function setExposeStacks(value: boolean): void {\n  exposeStackConfig = value;\n}\nfunction shouldExposeStack(): boolean {\n  return exposeStackConfig;\n}\n\n/** Reads a string field from a serialized error's context bag, with a safe fallback. */\nexport function ctxString(\n  ctx: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n  fallback = ''\n): string {\n  const value = ctx?.[key];\n  return typeof value === 'string' ? value : fallback;\n}\n\n/** Reads a number field from a serialized error's context bag, with a safe fallback. */\nexport function ctxNumber(\n  ctx: Readonly<Record<string, unknown>> | undefined,\n  key: string,\n  fallback = 0\n): number {\n  const value = ctx?.[key];\n  return typeof value === 'number' ? value : fallback;\n}\n\nfunction serializeCause(cause: unknown): SerializedCause | undefined {\n  if (!cause) return undefined;\n  if (cause instanceof OctoFlowError) {\n    return { name: cause.name, message: cause.message, code: cause.code };\n  }\n  if (cause instanceof Error) {\n    return { name: cause.name, message: cause.message };\n  }\n  if (typeof cause === 'string') {\n    return { message: cause };\n  }\n  try {\n    return { message: JSON.stringify(cause) };\n  } catch {\n    return { message: Object.prototype.toString.call(cause) };\n  }\n}\n\n/** Common base class for all octoflow errors. */\nexport class OctoFlowError extends Error {\n  readonly code: string;\n  readonly context: Readonly<Record<string, unknown>>;\n\n  constructor(\n    code: string,\n    message: string,\n    context: Record<string, unknown> = {}\n  ) {\n    super(message);\n    this.name = 'OctoFlowError';\n    this.code = code;\n    this.context = Object.freeze({ ...context });\n    // Ensure stack traces in V8/Node.js point to the actual throw site,\n    // not to the base Error constructor internals.\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor);\n    }\n  }\n\n  toJSON(): SerializedError {\n    const payload: SerializedError = {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n    };\n    if (Object.keys(this.context).length > 0) payload.context = this.context;\n    const cause = serializeCause((this as { cause?: unknown }).cause);\n    if (cause) payload.cause = cause;\n    if (shouldExposeStack() && this.stack) payload.stack = this.stack;\n    return payload;\n  }\n}\n\n/**\n * Rebuild an {@link OctoFlowError} from a {@link SerializedError} payload.\n * Falls back to the generic base class when the `code` is unknown (never\n * throws \u2014 callers prefer a best-effort reconstruction over an exception).\n */\nexport function deserializeError(payload: SerializedError): OctoFlowError {\n  const factory = ERROR_CLASS_BY_CODE.get(payload.code);\n  const err = factory\n    ? factory(payload)\n    : new OctoFlowError(payload.code, payload.message, payload.context ?? {});\n  if (!factory) err.name = payload.name;\n  if (payload.stack) err.stack = payload.stack;\n  return err;\n}\n"],
+  "mappings": "AA0BA,MAAM,sBAAsB,oBAAI,IAA0B;AAGnD,SAAS,mBAAmB,MAAc,SAA6B;AAC5E,sBAAoB,IAAI,MAAM,OAAO;AACvC;AAGO,SAAS,uBAA0C;AACxD,SAAO,MAAM,KAAK,oBAAoB,KAAK,CAAC;AAC9C;AAEA,IAAI,oBAAoB;AAMjB,SAAS,gBAAgB,OAAsB;AACpD,sBAAoB;AACtB;AACA,SAAS,oBAA6B;AACpC,SAAO;AACT;AAGO,SAAS,UACd,KACA,KACA,WAAW,IACH;AACR,QAAM,QAAQ,MAAM,GAAG;AACvB,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAGO,SAAS,UACd,KACA,KACA,WAAW,GACH;AACR,QAAM,QAAQ,MAAM,GAAG;AACvB,SAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;AAEA,SAAS,eAAe,OAA6C;AACnE,MAAI,CAAC,MAAO,QAAO;AACnB,MAAI,iBAAiB,eAAe;AAClC,WAAO,EAAE,MAAM,MAAM,MAAM,SAAS,MAAM,SAAS,MAAM,MAAM,KAAK;AAAA,EACtE;AACA,MAAI,iBAAiB,OAAO;AAC1B,WAAO,EAAE,MAAM,MAAM,MAAM,SAAS,MAAM,QAAQ;AAAA,EACpD;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,EAAE,SAAS,MAAM;AAAA,EAC1B;AACA,MAAI;AACF,WAAO,EAAE,SAAS,KAAK,UAAU,KAAK,EAAE;AAAA,EAC1C,QAAQ;AACN,WAAO,EAAE,SAAS,OAAO,UAAU,SAAS,KAAK,KAAK,EAAE;AAAA,EAC1D;AACF;AAGO,MAAM,sBAAsB,MAAM;AAAA,EAC9B;AAAA,EACA;AAAA,EAET,YACE,MACA,SACA,UAAmC,CAAC,GACpC;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,UAAU,OAAO,OAAO,EAAE,GAAG,QAAQ,CAAC;AAG3C,QAAI,MAAM,mBAAmB;AAC3B,YAAM,kBAAkB,MAAM,KAAK,WAAW;AAAA,IAChD;AAAA,EACF;AAAA,EAEA,SAA0B;AACxB,UAAM,UAA2B;AAAA,MAC/B,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,MACX,SAAS,KAAK;AAAA,IAChB;AACA,QAAI,OAAO,KAAK,KAAK,OAAO,EAAE,SAAS,EAAG,SAAQ,UAAU,KAAK;AACjE,UAAM,QAAQ,eAAgB,KAA6B,KAAK;AAChE,QAAI,MAAO,SAAQ,QAAQ;AAC3B,QAAI,kBAAkB,KAAK,KAAK,MAAO,SAAQ,QAAQ,KAAK;AAC5D,WAAO;AAAA,EACT;AACF;AAOO,SAAS,iBAAiB,SAAyC;AACxE,QAAM,UAAU,oBAAoB,IAAI,QAAQ,IAAI;AACpD,QAAM,MAAM,UACR,QAAQ,OAAO,IACf,IAAI,cAAc,QAAQ,MAAM,QAAQ,SAAS,QAAQ,WAAW,CAAC,CAAC;AAC1E,MAAI,CAAC,QAAS,KAAI,OAAO,QAAQ;AACjC,MAAI,QAAQ,MAAO,KAAI,QAAQ,QAAQ;AACvC,SAAO;AACT;",
+  "names": []
+}

package/dist/domain/errors/domain.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Aggregator of every domain error class. Split from a single 511-LOC file
+ * into seven cohesive modules — one per ownership area — to make the
+ * AGENTS.md ≤ 400-LOC source-budget enforceable. Importers can keep using
+ * `octoflow-core/domain/errors/domain.js` as-is, or import directly
+ * from the per-area files for narrower scopes.
+ */
+export { AgentRunError, AgentTimeoutError, SshConnectionError, UnsafeCommandError, } from './agent.js';
+export { ApiHttpError, ApiKeyError, ApiStreamError } from './api.js';
+export { ApprovalConcurrencyError, ApprovalNotFoundError, ApprovalStateError, } from './approval.js';
+export { BackendNotAvailableError, BackendSwitchLimitError, BackendSwitchRejectedError, BackendSwitchUnsupportedError, NoBackendAvailableError, } from './backend.js';
+export { OllamaAuthError, OllamaModelNotFoundError, OllamaNoModelsError, OllamaNotRunningError, OllamaToolResultMissingNameError, OllamaWebToolsAuthError, } from './ollama.js';
+export { SubagentConcurrencyLimitError, SubagentDepthExceededError, SubagentRoleNotFoundError, } from './subagent.js';
+export { BudgetExhaustedError, QueueFullError, SessionNotFoundError, TaskNotFoundError, TaskTerminalError, } from './task.js';
+//# sourceMappingURL=domain.d.ts.map

package/dist/domain/errors/domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/domain/errors/domain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,EAC7B,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,gCAAgC,EAChC,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}