@ai-matrx/agents 0.28.0 → 0.29.0

package/dist/portable/index.cjs

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// portable/index.ts
+var portable_exports = {};
+__export(portable_exports, {
+  PORTABLE_AGENT_CONTRACT: () => PORTABLE_AGENT_CONTRACT,
+  fetchPortableAgent: () => fetchPortableAgent,
+  fetchPortableAgentVersions: () => fetchPortableAgentVersions,
+  portableAgentPath: () => portableAgentPath,
+  summarizePortableAgent: () => summarizePortableAgent
+});
+module.exports = __toCommonJS(portable_exports);
+
+// matrx/transport.ts
+var MatrxApiError = class extends Error {
+  name = "MatrxApiError";
+  /** HTTP status of the failed response. */
+  status;
+  /** Machine code from the server body (`code`, or `detail.code`), when present. */
+  code;
+  /** The parsed server error body, verbatim (undefined when unparsable). */
+  serverDetail;
+  /** The request path the failure came from (server-relative). */
+  path;
+  constructor(args) {
+    super(
+      args.message ?? extractMatrxErrorMessage(args.serverDetail) ?? `HTTP ${args.status}`
+    );
+    this.status = args.status;
+    this.path = args.path;
+    this.serverDetail = args.serverDetail;
+    this.code = extractMatrxErrorCode(args.serverDetail);
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function extractMatrxErrorMessage(serverDetail) {
+  if (!isRecord(serverDetail)) return void 0;
+  const userMessage = nonBlankString(serverDetail.user_message);
+  if (userMessage) return userMessage;
+  const message = nonBlankString(serverDetail.message);
+  if (message) return message;
+  if (Array.isArray(serverDetail.details)) {
+    const messages = serverDetail.details.map((entry) => {
+      if (!isRecord(entry)) return void 0;
+      const detailMessage = nonBlankString(entry.message);
+      if (!detailMessage) return void 0;
+      const field = nonBlankString(entry.field);
+      return field ? `${field}: ${detailMessage}` : detailMessage;
+    }).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const detailMessage = nonBlankString(detail.message) ?? nonBlankString(detail.user_message);
+    if (detailMessage) return detailMessage;
+  }
+  if (typeof detail === "string" && detail.trim()) return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail.map(
+      (entry) => isRecord(entry) ? nonBlankString(entry.msg) : void 0
+    ).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  return void 0;
+}
+function extractMatrxErrorCode(serverDetail) {
+  if (!isRecord(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/internal.ts
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+
+// portable/types.generated.ts
+var PORTABLE_AGENT_CONTRACT = "portable-agent.v1";
+
+// portable/index.ts
+function portableAgentPath(target) {
+  return target.versionId ? `/ai/agents/versions/${encodePathSegment(target.versionId)}/portable` : `/ai/agents/${encodePathSegment(target.agentId ?? "")}/portable`;
+}
+function fetchPortableAgent(transport, target, options = {}) {
+  const body = {
+    variables: options.variables ?? {},
+    ...options.surface ? { surface: options.surface } : {}
+  };
+  return requestJson(transport, portableAgentPath(target), {
+    method: "POST",
+    body,
+    ...options.signal ? { signal: options.signal } : {}
+  });
+}
+function fetchPortableAgentVersions(transport, agentId, options = {}) {
+  return requestJson(
+    transport,
+    `/agent-service/agents/${encodePathSegment(agentId)}/versions`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+  );
+}
+function summarizePortableAgent(bundle) {
+  const missingSkills = bundle.unavailable.filter((u) => u.kind === "skill").length;
+  const missingTools = bundle.unavailable.filter((u) => u.kind === "tool").length;
+  return {
+    instructions: bundle.instructions.trim().length > 0,
+    skills: { loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },
+    tools: { loaded: bundle.tools.length, total: bundle.tools.length + missingTools }
+  };
+}
+//# sourceMappingURL=index.cjs.map

package/dist/portable/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../portable/index.ts","../../matrx/transport.ts","../../matrx/internal.ts","../../portable/types.generated.ts"],"sourcesContent":["/**\n * `@ai-matrx/agents/portable` — an AI Matrx agent as pieces a coding CLI loads.\n *\n * `fetchPortableAgent` reads `POST /ai/agents/{id}/portable` (or the version\n * door) and returns the server's `PortableAgentBundle`: the instructions with\n * the person's variable values filled, the skills as Claude `SKILL.md` files,\n * the server tools in MCP shape, and `unavailable[]` — what could not be\n * carried and why. The types are GENERATED from the server's Pydantic models\n * (`types.generated.ts`, `uv run python scripts/generate_types.py portable-agent`\n * in aidream), so the two cannot drift.\n *\n * Pure entry: no React, no Node, no I/O at import. Credentials and the\n * organization travel through the host's `MatrxTransport`\n * (`createMatrxTransport({ credentials, organizationId })`).\n */\n\nimport { encodePathSegment, requestJson } from \"../matrx/internal\";\nimport type { MatrxTransport } from \"../matrx/transport\";\nimport type {\n  JsonValue,\n  PortableAgentBundle,\n  PortableAgentRequest,\n} from \"./types.generated\";\n\nexport * from \"./types.generated\";\n\n/** Which definition to load: the agent's current one, or one immutable version. */\nexport type PortableAgentTarget =\n  | { agentId: string; versionId?: undefined }\n  | { versionId: string; agentId?: string | undefined };\n\nexport interface FetchPortableAgentOptions {\n  /** The person's values, by variable name. Unfilled variables use the agent's defaults. */\n  variables?: Record<string, JsonValue>;\n  /** The `ui.ui_surface` tools resolve on. Default: the server's coding-session surface. */\n  surface?: string;\n  signal?: AbortSignal;\n}\n\n/** The server path for a target — exported so a host's tests can assert it. */\nexport function portableAgentPath(target: PortableAgentTarget): string {\n  return target.versionId\n    ? `/ai/agents/versions/${encodePathSegment(target.versionId)}/portable`\n    : `/ai/agents/${encodePathSegment(target.agentId ?? \"\")}/portable`;\n}\n\n/**\n * Load one agent as a portable bundle. Throws `MatrxApiError` on refusal —\n * 401 signed out, 404 not found or not shared with this person.\n */\nexport function fetchPortableAgent(\n  transport: MatrxTransport,\n  target: PortableAgentTarget,\n  options: FetchPortableAgentOptions = {},\n): Promise<PortableAgentBundle> {\n  const body: PortableAgentRequest = {\n    variables: options.variables ?? {},\n    ...(options.surface ? { surface: options.surface } : {}),\n  };\n  return requestJson<PortableAgentBundle>(transport, portableAgentPath(target), {\n    method: \"POST\",\n    body,\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n}\n\n/** One saved version of an agent (`AgentVersionInfo` server-side). */\nexport interface PortableAgentVersion {\n  id: string;\n  agent_id: string;\n  version_number: number;\n  name: string;\n  change_note: string | null;\n  changed_at: string | null;\n}\n\n/**\n * The agent's saved versions, oldest first (`GET /agent-service/agents/{id}/versions`,\n * authorized through the same viewer rule as the agent). Feeds a version menu.\n */\nexport function fetchPortableAgentVersions(\n  transport: MatrxTransport,\n  agentId: string,\n  options: { signal?: AbortSignal } = {},\n): Promise<PortableAgentVersion[]> {\n  return requestJson<PortableAgentVersion[]>(\n    transport,\n    `/agent-service/agents/${encodePathSegment(agentId)}/versions`,\n    { method: \"GET\", ...(options.signal ? { signal: options.signal } : {}) },\n  );\n}\n\n/** What a bundle loaded, counted — what a header chip shows. */\nexport interface PortableAgentLoadSummary {\n  instructions: boolean;\n  skills: { loaded: number; total: number };\n  tools: { loaded: number; total: number };\n}\n\n/** Count what a bundle carries against what the agent declares. */\nexport function summarizePortableAgent(bundle: PortableAgentBundle): PortableAgentLoadSummary {\n  const missingSkills = bundle.unavailable.filter((u) => u.kind === \"skill\").length;\n  const missingTools = bundle.unavailable.filter((u) => u.kind === \"tool\").length;\n  return {\n    instructions: bundle.instructions.trim().length > 0,\n    skills: { loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },\n    tools: { loaded: bundle.tools.length, total: bundle.tools.length + missingTools },\n  };\n}\n","/**\n * `@ai-matrx/agents/matrx` — the Matrx transport port.\n *\n * The ONE seam between this package's wire semantics and a host's connection\n * policy. This package owns WHAT is said to the AI Matrx server — paths,\n * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor\n * header — and the host owns HOW the connection is made:\n *\n * - base-URL / backend-channel resolution (global, sandbox override, local\n *   engine, EC2-dedicated — whatever ladder the host runs);\n * - credentials (Supabase JWT `Authorization: Bearer`, guest\n *   `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;\n * - the `X-Organization-Id` context header;\n * - retry policy, network-level timeouts, and diagnostics capture.\n *\n * A host implements the port in a few lines:\n *\n * ```ts\n * const transport: MatrxTransport = {\n *   fetch: (path, init) =>\n *     fetch(`${baseUrl}${path}`, {\n *       ...init,\n *       headers: { ...init.headers, ...authHeaders() },\n *     }),\n * };\n * ```\n *\n * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s\n * `/api` transport can implement it without importing this package.\n */\n\n/**\n * The request this package hands the port. A strict subset of `RequestInit`,\n * so a host can spread it straight into `fetch`.\n */\nexport interface MatrxTransportRequest {\n  method: \"GET\" | \"POST\";\n  /**\n   * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,\n   * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;\n   * it must not drop these.\n   */\n  headers: Record<string, string>;\n  /** Pre-serialized JSON body, present on POST calls that carry one. */\n  body?: string;\n  /** Caller cancellation. The host must wire it to the underlying fetch. */\n  signal?: AbortSignal;\n}\n\n/**\n * The transport port. `path` is server-relative and always starts with `/`\n * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.\n */\nexport interface MatrxTransport {\n  fetch(path: string, init: MatrxTransportRequest): Promise<Response>;\n}\n\n/**\n * A non-2xx response from the Matrx API, with the server's structured error\n * body preserved and its richest human-readable message extracted.\n */\nexport class MatrxApiError extends Error {\n  override readonly name = \"MatrxApiError\";\n  /** HTTP status of the failed response. */\n  readonly status: number;\n  /** Machine code from the server body (`code`, or `detail.code`), when present. */\n  readonly code: string | null;\n  /** The parsed server error body, verbatim (undefined when unparsable). */\n  readonly serverDetail: unknown;\n  /** The request path the failure came from (server-relative). */\n  readonly path: string;\n\n  constructor(args: {\n    status: number;\n    path: string;\n    serverDetail?: unknown;\n    message?: string;\n  }) {\n    super(\n      args.message ??\n        extractMatrxErrorMessage(args.serverDetail) ??\n        `HTTP ${args.status}`,\n    );\n    this.status = args.status;\n    this.path = args.path;\n    this.serverDetail = args.serverDetail;\n    this.code = extractMatrxErrorCode(args.serverDetail);\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction nonBlankString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.trim() ? value : undefined;\n}\n\n/**\n * Extract the richest human-readable message from a Matrx/FastAPI error body.\n *\n * aidream 4xx validation errors look like\n * `{ error, user_message, details: [{ field, message, help }] }`; hand-raised\n * HTTPExceptions carry `{ detail: { code, message } }`; FastAPI's defaults are\n * `{ detail: string | [{ msg }] }`. Preference order: `user_message` →\n * `message` → joined `details[].message` → `detail.message` →\n * `detail` string → joined `detail[].msg`. Returns undefined for\n * unrecognized bodies so callers fall back to the bare status line.\n */\nexport function extractMatrxErrorMessage(\n  serverDetail: unknown,\n): string | undefined {\n  if (!isRecord(serverDetail)) return undefined;\n\n  const userMessage = nonBlankString(serverDetail.user_message);\n  if (userMessage) return userMessage;\n  const message = nonBlankString(serverDetail.message);\n  if (message) return message;\n\n  if (Array.isArray(serverDetail.details)) {\n    const messages = serverDetail.details\n      .map((entry: unknown) => {\n        if (!isRecord(entry)) return undefined;\n        const detailMessage = nonBlankString(entry.message);\n        if (!detailMessage) return undefined;\n        const field = nonBlankString(entry.field);\n        return field ? `${field}: ${detailMessage}` : detailMessage;\n      })\n      .filter((m): m is string => typeof m === \"string\");\n    if (messages.length > 0) return messages.join(\"; \");\n  }\n\n  const detail = serverDetail.detail;\n  if (isRecord(detail)) {\n    const detailMessage =\n      nonBlankString(detail.message) ?? nonBlankString(detail.user_message);\n    if (detailMessage) return detailMessage;\n  }\n  if (typeof detail === \"string\" && detail.trim()) return detail;\n  if (Array.isArray(detail)) {\n    const messages = detail\n      .map((entry: unknown) =>\n        isRecord(entry) ? nonBlankString(entry.msg) : undefined,\n      )\n      .filter((m): m is string => typeof m === \"string\");\n    if (messages.length > 0) return messages.join(\"; \");\n  }\n  return undefined;\n}\n\n/**\n * Extract the machine error code from a Matrx error body: top-level `code`,\n * else `detail.code` (the hand-raised HTTPException shape). Null when absent.\n */\nexport function extractMatrxErrorCode(serverDetail: unknown): string | null {\n  if (!isRecord(serverDetail)) return null;\n  const topLevel = nonBlankString(serverDetail.code);\n  if (topLevel) return topLevel;\n  const detail = serverDetail.detail;\n  if (isRecord(detail)) {\n    const nested = nonBlankString(detail.code);\n    if (nested) return nested;\n  }\n  return null;\n}\n","/**\n * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the\n * public surface — `matrx/index.ts` deliberately does not re-export this\n * module. Everything here is pure: no globals, no work at import time.\n */\n\nimport {\n  readMatrxNdjsonStream,\n  type MatrxNdjsonIssue,\n  type MatrxStreamEnvelope,\n  type MatrxStreamEnvelopeObservation,\n} from \"../stream/ndjson\";\nimport { MatrxApiError, type MatrxTransport } from \"./transport\";\n\n/** Encode one path segment (an id) safely into a server-relative path. */\nexport function encodePathSegment(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport type QueryValue =\n  | string\n  | number\n  | boolean\n  | readonly string[]\n  | undefined;\n\n/**\n * Build a query string. Array values repeat the key (`kind=a&kind=b` — the\n * FastAPI repeatable-parameter convention); undefined values are omitted.\n * Returns \"\" or a string starting with \"?\".\n */\nexport function buildQuery(params: Record<string, QueryValue>): string {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined) continue;\n    if (Array.isArray(value)) {\n      for (const entry of value) search.append(key, entry);\n    } else {\n      search.append(key, String(value));\n    }\n  }\n  const encoded = search.toString();\n  return encoded ? `?${encoded}` : \"\";\n}\n\nasync function readServerDetail(response: Response): Promise<unknown> {\n  try {\n    return (await response.json()) as unknown;\n  } catch {\n    return undefined;\n  }\n}\n\nasync function throwApiError(path: string, response: Response): Promise<never> {\n  throw new MatrxApiError({\n    status: response.status,\n    path,\n    serverDetail: await readServerDetail(response),\n  });\n}\n\nexport interface JsonRequestOptions {\n  method: \"GET\" | \"POST\";\n  body?: unknown;\n  signal?: AbortSignal;\n}\n\n/**\n * Execute a JSON request through the transport. Throws `MatrxApiError` on a\n * non-2xx response; resolves with the parsed JSON body otherwise.\n */\nexport async function requestJson<T>(\n  transport: MatrxTransport,\n  path: string,\n  options: JsonRequestOptions,\n): Promise<T> {\n  const hasBody = options.method !== \"GET\" && options.body !== undefined;\n  const response = await transport.fetch(path, {\n    method: options.method,\n    headers: hasBody ? { \"Content-Type\": \"application/json\" } : {},\n    ...(hasBody ? { body: JSON.stringify(options.body) } : {}),\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n  if (!response.ok) return throwApiError(path, response);\n  return (await response.json()) as T;\n}\n\n/**\n * Options for every streaming call, riding the NDJSON kernel's contract.\n * Public via `./run`'s re-export.\n */\nexport interface MatrxStreamCallOptions {\n  /** Abort the fetch and end the events iterator. */\n  signal?: AbortSignal;\n  /** Bounded background read-ahead (see `stream/ndjson`). */\n  maxReadAhead?: number;\n  /** Malformed NDJSON is non-fatal but must never disappear silently. */\n  onMalformedLine?: (issue: MatrxNdjsonIssue) => void;\n  /** Valid JSON with no recognized Matrx envelope. */\n  onUnknownEnvelope?: (value: unknown) => void;\n  /** Observe every valid envelope in its exact wire form. */\n  onValidEnvelope?: (observation: MatrxStreamEnvelopeObservation) => void;\n}\n\n/**\n * A live agent run: the server-assigned ids (from response headers, available\n * BEFORE any event) and the normalized event stream. Public via `./run`.\n */\nexport interface MatrxRunHandle {\n  /** `X-Request-ID` — the ONLY id `POST /ai/cancel/{request_id}` accepts. */\n  requestId: string | null;\n  /** `X-Conversation-ID` — the server's conversation identity. */\n  conversationId: string | null;\n  /** Normalized `{event, data}` envelopes through the ONE wire kernel. */\n  events: AsyncGenerator<MatrxStreamEnvelope, void, undefined>;\n  /** The raw response, for hosts that need headers/status beyond the ids. */\n  response: Response;\n}\n\n/**\n * Wrap a validated streaming Response into the run handle — the ONE place\n * the id headers are read and the NDJSON kernel is attached (`./run` and\n * `./operations`' rejoin share it).\n */\nexport function toRunHandle(\n  response: Response,\n  options: MatrxStreamCallOptions,\n): MatrxRunHandle {\n  return {\n    requestId: response.headers.get(\"X-Request-ID\"),\n    conversationId: response.headers.get(\"X-Conversation-ID\"),\n    events: readMatrxNdjsonStream(response.body as ReadableStream<Uint8Array>, {\n      ...(options.signal ? { signal: options.signal } : {}),\n      ...(options.maxReadAhead !== undefined\n        ? { maxReadAhead: options.maxReadAhead }\n        : {}),\n      ...(options.onMalformedLine\n        ? { onMalformedLine: options.onMalformedLine }\n        : {}),\n      ...(options.onUnknownEnvelope\n        ? { onUnknownEnvelope: options.onUnknownEnvelope }\n        : {}),\n      ...(options.onValidEnvelope\n        ? { onValidEnvelope: options.onValidEnvelope }\n        : {}),\n    }),\n    response,\n  };\n}\n\nexport interface StreamRequestOptions {\n  method: \"GET\" | \"POST\";\n  body?: unknown;\n  /** Extra wire-semantic headers (`Accept`, `Last-Event-ID`). */\n  headers?: Record<string, string>;\n  signal?: AbortSignal;\n}\n\n/**\n * Execute a streaming request. Throws `MatrxApiError` on a non-2xx response\n * (reading the error body as JSON when possible) or when a 2xx response\n * carries no body; resolves with the validated `Response` otherwise.\n */\nexport async function requestStream(\n  transport: MatrxTransport,\n  path: string,\n  options: StreamRequestOptions,\n): Promise<Response> {\n  const hasBody = options.method !== \"GET\" && options.body !== undefined;\n  const response = await transport.fetch(path, {\n    method: options.method,\n    headers: {\n      ...(hasBody ? { \"Content-Type\": \"application/json\" } : {}),\n      ...options.headers,\n    },\n    ...(hasBody ? { body: JSON.stringify(options.body) } : {}),\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n  if (!response.ok) return throwApiError(path, response);\n  if (!response.body) {\n    throw new MatrxApiError({\n      status: response.status,\n      path,\n      serverDetail: { code: \"missing_response_body\" },\n      message: \"The streaming response carried no body.\",\n    });\n  }\n  return response;\n}\n","// AUTO-GENERATED — do not edit by hand.\n// Source: aidream/services/agent_service/portable.py\n// Run: uv run python scripts/generate_types.py portable-agent\n\nexport const PORTABLE_AGENT_CONTRACT = \"portable-agent.v1\";\n\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\nexport interface PortableAgentRequest {\n  variables?: Record<string, JsonValue>;\n  surface?: string;\n}\n\nexport interface PortableSkill {\n  id: string;\n  tier: \"included\" | \"listed\";\n  slug: string;\n  label: string;\n  description: string;\n  path: string;\n  content: string;\n  body: string;\n  content_hash: string;\n}\n\nexport interface PortableTool {\n  name: string;\n  canonical_name: string;\n  description: string;\n  parameters: Record<string, JsonValue>;\n}\n\nexport interface PortableUnavailable {\n  kind: \"tool\" | \"skill\" | \"variable\" | \"message\" | \"mcp_server\" | \"tools\";\n  name: string;\n  reason: string;\n}\n\nexport interface PortableAgentBundle {\n  contract: \"portable-agent.v1\";\n  agent_id: string;\n  version_id: string | null;\n  version_number: number | null;\n  is_version: boolean;\n  name: string;\n  definition_hash: string;\n  model_id: string;\n  instructions: string;\n  variables: Record<string, JsonValue>[];\n  filled_variables: string[];\n  skills: PortableSkill[];\n  tools: PortableTool[];\n  surface: string;\n  unavailable: PortableUnavailable[];\n}\n"],"mappings":"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","names":[]}

package/dist/portable/index.d.cts

@@ -0,0 +1,74 @@
+import { M as MatrxTransport } from '../transport-CxD0fL8p.cjs';
+import { J as JsonValue, P as PortableAgentBundle } from '../types.generated-BydVlqDC.cjs';
+export { a as PORTABLE_AGENT_CONTRACT, b as PortableAgentRequest, c as PortableSkill, d as PortableTool, e as PortableUnavailable } from '../types.generated-BydVlqDC.cjs';
+
+/**
+ * `@ai-matrx/agents/portable` — an AI Matrx agent as pieces a coding CLI loads.
+ *
+ * `fetchPortableAgent` reads `POST /ai/agents/{id}/portable` (or the version
+ * door) and returns the server's `PortableAgentBundle`: the instructions with
+ * the person's variable values filled, the skills as Claude `SKILL.md` files,
+ * the server tools in MCP shape, and `unavailable[]` — what could not be
+ * carried and why. The types are GENERATED from the server's Pydantic models
+ * (`types.generated.ts`, `uv run python scripts/generate_types.py portable-agent`
+ * in aidream), so the two cannot drift.
+ *
+ * Pure entry: no React, no Node, no I/O at import. Credentials and the
+ * organization travel through the host's `MatrxTransport`
+ * (`createMatrxTransport({ credentials, organizationId })`).
+ */
+
+/** Which definition to load: the agent's current one, or one immutable version. */
+type PortableAgentTarget = {
+    agentId: string;
+    versionId?: undefined;
+} | {
+    versionId: string;
+    agentId?: string | undefined;
+};
+interface FetchPortableAgentOptions {
+    /** The person's values, by variable name. Unfilled variables use the agent's defaults. */
+    variables?: Record<string, JsonValue>;
+    /** The `ui.ui_surface` tools resolve on. Default: the server's coding-session surface. */
+    surface?: string;
+    signal?: AbortSignal;
+}
+/** The server path for a target — exported so a host's tests can assert it. */
+declare function portableAgentPath(target: PortableAgentTarget): string;
+/**
+ * Load one agent as a portable bundle. Throws `MatrxApiError` on refusal —
+ * 401 signed out, 404 not found or not shared with this person.
+ */
+declare function fetchPortableAgent(transport: MatrxTransport, target: PortableAgentTarget, options?: FetchPortableAgentOptions): Promise<PortableAgentBundle>;
+/** One saved version of an agent (`AgentVersionInfo` server-side). */
+interface PortableAgentVersion {
+    id: string;
+    agent_id: string;
+    version_number: number;
+    name: string;
+    change_note: string | null;
+    changed_at: string | null;
+}
+/**
+ * The agent's saved versions, oldest first (`GET /agent-service/agents/{id}/versions`,
+ * authorized through the same viewer rule as the agent). Feeds a version menu.
+ */
+declare function fetchPortableAgentVersions(transport: MatrxTransport, agentId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<PortableAgentVersion[]>;
+/** What a bundle loaded, counted — what a header chip shows. */
+interface PortableAgentLoadSummary {
+    instructions: boolean;
+    skills: {
+        loaded: number;
+        total: number;
+    };
+    tools: {
+        loaded: number;
+        total: number;
+    };
+}
+/** Count what a bundle carries against what the agent declares. */
+declare function summarizePortableAgent(bundle: PortableAgentBundle): PortableAgentLoadSummary;
+
+export { type FetchPortableAgentOptions, JsonValue, PortableAgentBundle, type PortableAgentLoadSummary, type PortableAgentTarget, type PortableAgentVersion, fetchPortableAgent, fetchPortableAgentVersions, portableAgentPath, summarizePortableAgent };

package/dist/portable/index.d.ts

@@ -0,0 +1,74 @@
+import { M as MatrxTransport } from '../transport-CxD0fL8p.js';
+import { J as JsonValue, P as PortableAgentBundle } from '../types.generated-BydVlqDC.js';
+export { a as PORTABLE_AGENT_CONTRACT, b as PortableAgentRequest, c as PortableSkill, d as PortableTool, e as PortableUnavailable } from '../types.generated-BydVlqDC.js';
+
+/**
+ * `@ai-matrx/agents/portable` — an AI Matrx agent as pieces a coding CLI loads.
+ *
+ * `fetchPortableAgent` reads `POST /ai/agents/{id}/portable` (or the version
+ * door) and returns the server's `PortableAgentBundle`: the instructions with
+ * the person's variable values filled, the skills as Claude `SKILL.md` files,
+ * the server tools in MCP shape, and `unavailable[]` — what could not be
+ * carried and why. The types are GENERATED from the server's Pydantic models
+ * (`types.generated.ts`, `uv run python scripts/generate_types.py portable-agent`
+ * in aidream), so the two cannot drift.
+ *
+ * Pure entry: no React, no Node, no I/O at import. Credentials and the
+ * organization travel through the host's `MatrxTransport`
+ * (`createMatrxTransport({ credentials, organizationId })`).
+ */
+
+/** Which definition to load: the agent's current one, or one immutable version. */
+type PortableAgentTarget = {
+    agentId: string;
+    versionId?: undefined;
+} | {
+    versionId: string;
+    agentId?: string | undefined;
+};
+interface FetchPortableAgentOptions {
+    /** The person's values, by variable name. Unfilled variables use the agent's defaults. */
+    variables?: Record<string, JsonValue>;
+    /** The `ui.ui_surface` tools resolve on. Default: the server's coding-session surface. */
+    surface?: string;
+    signal?: AbortSignal;
+}
+/** The server path for a target — exported so a host's tests can assert it. */
+declare function portableAgentPath(target: PortableAgentTarget): string;
+/**
+ * Load one agent as a portable bundle. Throws `MatrxApiError` on refusal —
+ * 401 signed out, 404 not found or not shared with this person.
+ */
+declare function fetchPortableAgent(transport: MatrxTransport, target: PortableAgentTarget, options?: FetchPortableAgentOptions): Promise<PortableAgentBundle>;
+/** One saved version of an agent (`AgentVersionInfo` server-side). */
+interface PortableAgentVersion {
+    id: string;
+    agent_id: string;
+    version_number: number;
+    name: string;
+    change_note: string | null;
+    changed_at: string | null;
+}
+/**
+ * The agent's saved versions, oldest first (`GET /agent-service/agents/{id}/versions`,
+ * authorized through the same viewer rule as the agent). Feeds a version menu.
+ */
+declare function fetchPortableAgentVersions(transport: MatrxTransport, agentId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<PortableAgentVersion[]>;
+/** What a bundle loaded, counted — what a header chip shows. */
+interface PortableAgentLoadSummary {
+    instructions: boolean;
+    skills: {
+        loaded: number;
+        total: number;
+    };
+    tools: {
+        loaded: number;
+        total: number;
+    };
+}
+/** Count what a bundle carries against what the agent declares. */
+declare function summarizePortableAgent(bundle: PortableAgentBundle): PortableAgentLoadSummary;
+
+export { type FetchPortableAgentOptions, JsonValue, PortableAgentBundle, type PortableAgentLoadSummary, type PortableAgentTarget, type PortableAgentVersion, fetchPortableAgent, fetchPortableAgentVersions, portableAgentPath, summarizePortableAgent };

package/dist/portable/index.js

@@ -0,0 +1,141 @@
+// matrx/transport.ts
+var MatrxApiError = class extends Error {
+  name = "MatrxApiError";
+  /** HTTP status of the failed response. */
+  status;
+  /** Machine code from the server body (`code`, or `detail.code`), when present. */
+  code;
+  /** The parsed server error body, verbatim (undefined when unparsable). */
+  serverDetail;
+  /** The request path the failure came from (server-relative). */
+  path;
+  constructor(args) {
+    super(
+      args.message ?? extractMatrxErrorMessage(args.serverDetail) ?? `HTTP ${args.status}`
+    );
+    this.status = args.status;
+    this.path = args.path;
+    this.serverDetail = args.serverDetail;
+    this.code = extractMatrxErrorCode(args.serverDetail);
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim() ? value : void 0;
+}
+function extractMatrxErrorMessage(serverDetail) {
+  if (!isRecord(serverDetail)) return void 0;
+  const userMessage = nonBlankString(serverDetail.user_message);
+  if (userMessage) return userMessage;
+  const message = nonBlankString(serverDetail.message);
+  if (message) return message;
+  if (Array.isArray(serverDetail.details)) {
+    const messages = serverDetail.details.map((entry) => {
+      if (!isRecord(entry)) return void 0;
+      const detailMessage = nonBlankString(entry.message);
+      if (!detailMessage) return void 0;
+      const field = nonBlankString(entry.field);
+      return field ? `${field}: ${detailMessage}` : detailMessage;
+    }).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const detailMessage = nonBlankString(detail.message) ?? nonBlankString(detail.user_message);
+    if (detailMessage) return detailMessage;
+  }
+  if (typeof detail === "string" && detail.trim()) return detail;
+  if (Array.isArray(detail)) {
+    const messages = detail.map(
+      (entry) => isRecord(entry) ? nonBlankString(entry.msg) : void 0
+    ).filter((m) => typeof m === "string");
+    if (messages.length > 0) return messages.join("; ");
+  }
+  return void 0;
+}
+function extractMatrxErrorCode(serverDetail) {
+  if (!isRecord(serverDetail)) return null;
+  const topLevel = nonBlankString(serverDetail.code);
+  if (topLevel) return topLevel;
+  const detail = serverDetail.detail;
+  if (isRecord(detail)) {
+    const nested = nonBlankString(detail.code);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// matrx/internal.ts
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+async function readServerDetail(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
+async function throwApiError(path, response) {
+  throw new MatrxApiError({
+    status: response.status,
+    path,
+    serverDetail: await readServerDetail(response)
+  });
+}
+async function requestJson(transport, path, options) {
+  const hasBody = options.method !== "GET" && options.body !== void 0;
+  const response = await transport.fetch(path, {
+    method: options.method,
+    headers: hasBody ? { "Content-Type": "application/json" } : {},
+    ...hasBody ? { body: JSON.stringify(options.body) } : {},
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  if (!response.ok) return throwApiError(path, response);
+  return await response.json();
+}
+
+// portable/types.generated.ts
+var PORTABLE_AGENT_CONTRACT = "portable-agent.v1";
+
+// portable/index.ts
+function portableAgentPath(target) {
+  return target.versionId ? `/ai/agents/versions/${encodePathSegment(target.versionId)}/portable` : `/ai/agents/${encodePathSegment(target.agentId ?? "")}/portable`;
+}
+function fetchPortableAgent(transport, target, options = {}) {
+  const body = {
+    variables: options.variables ?? {},
+    ...options.surface ? { surface: options.surface } : {}
+  };
+  return requestJson(transport, portableAgentPath(target), {
+    method: "POST",
+    body,
+    ...options.signal ? { signal: options.signal } : {}
+  });
+}
+function fetchPortableAgentVersions(transport, agentId, options = {}) {
+  return requestJson(
+    transport,
+    `/agent-service/agents/${encodePathSegment(agentId)}/versions`,
+    { method: "GET", ...options.signal ? { signal: options.signal } : {} }
+  );
+}
+function summarizePortableAgent(bundle) {
+  const missingSkills = bundle.unavailable.filter((u) => u.kind === "skill").length;
+  const missingTools = bundle.unavailable.filter((u) => u.kind === "tool").length;
+  return {
+    instructions: bundle.instructions.trim().length > 0,
+    skills: { loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },
+    tools: { loaded: bundle.tools.length, total: bundle.tools.length + missingTools }
+  };
+}
+export {
+  PORTABLE_AGENT_CONTRACT,
+  fetchPortableAgent,
+  fetchPortableAgentVersions,
+  portableAgentPath,
+  summarizePortableAgent
+};
+//# sourceMappingURL=index.js.map

package/dist/portable/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../matrx/transport.ts","../../matrx/internal.ts","../../portable/types.generated.ts","../../portable/index.ts"],"sourcesContent":["/**\n * `@ai-matrx/agents/matrx` — the Matrx transport port.\n *\n * The ONE seam between this package's wire semantics and a host's connection\n * policy. This package owns WHAT is said to the AI Matrx server — paths,\n * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor\n * header — and the host owns HOW the connection is made:\n *\n * - base-URL / backend-channel resolution (global, sandbox override, local\n *   engine, EC2-dedicated — whatever ladder the host runs);\n * - credentials (Supabase JWT `Authorization: Bearer`, guest\n *   `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;\n * - the `X-Organization-Id` context header;\n * - retry policy, network-level timeouts, and diagnostics capture.\n *\n * A host implements the port in a few lines:\n *\n * ```ts\n * const transport: MatrxTransport = {\n *   fetch: (path, init) =>\n *     fetch(`${baseUrl}${path}`, {\n *       ...init,\n *       headers: { ...init.headers, ...authHeaders() },\n *     }),\n * };\n * ```\n *\n * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s\n * `/api` transport can implement it without importing this package.\n */\n\n/**\n * The request this package hands the port. A strict subset of `RequestInit`,\n * so a host can spread it straight into `fetch`.\n */\nexport interface MatrxTransportRequest {\n  method: \"GET\" | \"POST\";\n  /**\n   * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,\n   * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;\n   * it must not drop these.\n   */\n  headers: Record<string, string>;\n  /** Pre-serialized JSON body, present on POST calls that carry one. */\n  body?: string;\n  /** Caller cancellation. The host must wire it to the underlying fetch. */\n  signal?: AbortSignal;\n}\n\n/**\n * The transport port. `path` is server-relative and always starts with `/`\n * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.\n */\nexport interface MatrxTransport {\n  fetch(path: string, init: MatrxTransportRequest): Promise<Response>;\n}\n\n/**\n * A non-2xx response from the Matrx API, with the server's structured error\n * body preserved and its richest human-readable message extracted.\n */\nexport class MatrxApiError extends Error {\n  override readonly name = \"MatrxApiError\";\n  /** HTTP status of the failed response. */\n  readonly status: number;\n  /** Machine code from the server body (`code`, or `detail.code`), when present. */\n  readonly code: string | null;\n  /** The parsed server error body, verbatim (undefined when unparsable). */\n  readonly serverDetail: unknown;\n  /** The request path the failure came from (server-relative). */\n  readonly path: string;\n\n  constructor(args: {\n    status: number;\n    path: string;\n    serverDetail?: unknown;\n    message?: string;\n  }) {\n    super(\n      args.message ??\n        extractMatrxErrorMessage(args.serverDetail) ??\n        `HTTP ${args.status}`,\n    );\n    this.status = args.status;\n    this.path = args.path;\n    this.serverDetail = args.serverDetail;\n    this.code = extractMatrxErrorCode(args.serverDetail);\n  }\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction nonBlankString(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.trim() ? value : undefined;\n}\n\n/**\n * Extract the richest human-readable message from a Matrx/FastAPI error body.\n *\n * aidream 4xx validation errors look like\n * `{ error, user_message, details: [{ field, message, help }] }`; hand-raised\n * HTTPExceptions carry `{ detail: { code, message } }`; FastAPI's defaults are\n * `{ detail: string | [{ msg }] }`. Preference order: `user_message` →\n * `message` → joined `details[].message` → `detail.message` →\n * `detail` string → joined `detail[].msg`. Returns undefined for\n * unrecognized bodies so callers fall back to the bare status line.\n */\nexport function extractMatrxErrorMessage(\n  serverDetail: unknown,\n): string | undefined {\n  if (!isRecord(serverDetail)) return undefined;\n\n  const userMessage = nonBlankString(serverDetail.user_message);\n  if (userMessage) return userMessage;\n  const message = nonBlankString(serverDetail.message);\n  if (message) return message;\n\n  if (Array.isArray(serverDetail.details)) {\n    const messages = serverDetail.details\n      .map((entry: unknown) => {\n        if (!isRecord(entry)) return undefined;\n        const detailMessage = nonBlankString(entry.message);\n        if (!detailMessage) return undefined;\n        const field = nonBlankString(entry.field);\n        return field ? `${field}: ${detailMessage}` : detailMessage;\n      })\n      .filter((m): m is string => typeof m === \"string\");\n    if (messages.length > 0) return messages.join(\"; \");\n  }\n\n  const detail = serverDetail.detail;\n  if (isRecord(detail)) {\n    const detailMessage =\n      nonBlankString(detail.message) ?? nonBlankString(detail.user_message);\n    if (detailMessage) return detailMessage;\n  }\n  if (typeof detail === \"string\" && detail.trim()) return detail;\n  if (Array.isArray(detail)) {\n    const messages = detail\n      .map((entry: unknown) =>\n        isRecord(entry) ? nonBlankString(entry.msg) : undefined,\n      )\n      .filter((m): m is string => typeof m === \"string\");\n    if (messages.length > 0) return messages.join(\"; \");\n  }\n  return undefined;\n}\n\n/**\n * Extract the machine error code from a Matrx error body: top-level `code`,\n * else `detail.code` (the hand-raised HTTPException shape). Null when absent.\n */\nexport function extractMatrxErrorCode(serverDetail: unknown): string | null {\n  if (!isRecord(serverDetail)) return null;\n  const topLevel = nonBlankString(serverDetail.code);\n  if (topLevel) return topLevel;\n  const detail = serverDetail.detail;\n  if (isRecord(detail)) {\n    const nested = nonBlankString(detail.code);\n    if (nested) return nested;\n  }\n  return null;\n}\n","/**\n * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the\n * public surface — `matrx/index.ts` deliberately does not re-export this\n * module. Everything here is pure: no globals, no work at import time.\n */\n\nimport {\n  readMatrxNdjsonStream,\n  type MatrxNdjsonIssue,\n  type MatrxStreamEnvelope,\n  type MatrxStreamEnvelopeObservation,\n} from \"../stream/ndjson\";\nimport { MatrxApiError, type MatrxTransport } from \"./transport\";\n\n/** Encode one path segment (an id) safely into a server-relative path. */\nexport function encodePathSegment(value: string): string {\n  return encodeURIComponent(value);\n}\n\nexport type QueryValue =\n  | string\n  | number\n  | boolean\n  | readonly string[]\n  | undefined;\n\n/**\n * Build a query string. Array values repeat the key (`kind=a&kind=b` — the\n * FastAPI repeatable-parameter convention); undefined values are omitted.\n * Returns \"\" or a string starting with \"?\".\n */\nexport function buildQuery(params: Record<string, QueryValue>): string {\n  const search = new URLSearchParams();\n  for (const [key, value] of Object.entries(params)) {\n    if (value === undefined) continue;\n    if (Array.isArray(value)) {\n      for (const entry of value) search.append(key, entry);\n    } else {\n      search.append(key, String(value));\n    }\n  }\n  const encoded = search.toString();\n  return encoded ? `?${encoded}` : \"\";\n}\n\nasync function readServerDetail(response: Response): Promise<unknown> {\n  try {\n    return (await response.json()) as unknown;\n  } catch {\n    return undefined;\n  }\n}\n\nasync function throwApiError(path: string, response: Response): Promise<never> {\n  throw new MatrxApiError({\n    status: response.status,\n    path,\n    serverDetail: await readServerDetail(response),\n  });\n}\n\nexport interface JsonRequestOptions {\n  method: \"GET\" | \"POST\";\n  body?: unknown;\n  signal?: AbortSignal;\n}\n\n/**\n * Execute a JSON request through the transport. Throws `MatrxApiError` on a\n * non-2xx response; resolves with the parsed JSON body otherwise.\n */\nexport async function requestJson<T>(\n  transport: MatrxTransport,\n  path: string,\n  options: JsonRequestOptions,\n): Promise<T> {\n  const hasBody = options.method !== \"GET\" && options.body !== undefined;\n  const response = await transport.fetch(path, {\n    method: options.method,\n    headers: hasBody ? { \"Content-Type\": \"application/json\" } : {},\n    ...(hasBody ? { body: JSON.stringify(options.body) } : {}),\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n  if (!response.ok) return throwApiError(path, response);\n  return (await response.json()) as T;\n}\n\n/**\n * Options for every streaming call, riding the NDJSON kernel's contract.\n * Public via `./run`'s re-export.\n */\nexport interface MatrxStreamCallOptions {\n  /** Abort the fetch and end the events iterator. */\n  signal?: AbortSignal;\n  /** Bounded background read-ahead (see `stream/ndjson`). */\n  maxReadAhead?: number;\n  /** Malformed NDJSON is non-fatal but must never disappear silently. */\n  onMalformedLine?: (issue: MatrxNdjsonIssue) => void;\n  /** Valid JSON with no recognized Matrx envelope. */\n  onUnknownEnvelope?: (value: unknown) => void;\n  /** Observe every valid envelope in its exact wire form. */\n  onValidEnvelope?: (observation: MatrxStreamEnvelopeObservation) => void;\n}\n\n/**\n * A live agent run: the server-assigned ids (from response headers, available\n * BEFORE any event) and the normalized event stream. Public via `./run`.\n */\nexport interface MatrxRunHandle {\n  /** `X-Request-ID` — the ONLY id `POST /ai/cancel/{request_id}` accepts. */\n  requestId: string | null;\n  /** `X-Conversation-ID` — the server's conversation identity. */\n  conversationId: string | null;\n  /** Normalized `{event, data}` envelopes through the ONE wire kernel. */\n  events: AsyncGenerator<MatrxStreamEnvelope, void, undefined>;\n  /** The raw response, for hosts that need headers/status beyond the ids. */\n  response: Response;\n}\n\n/**\n * Wrap a validated streaming Response into the run handle — the ONE place\n * the id headers are read and the NDJSON kernel is attached (`./run` and\n * `./operations`' rejoin share it).\n */\nexport function toRunHandle(\n  response: Response,\n  options: MatrxStreamCallOptions,\n): MatrxRunHandle {\n  return {\n    requestId: response.headers.get(\"X-Request-ID\"),\n    conversationId: response.headers.get(\"X-Conversation-ID\"),\n    events: readMatrxNdjsonStream(response.body as ReadableStream<Uint8Array>, {\n      ...(options.signal ? { signal: options.signal } : {}),\n      ...(options.maxReadAhead !== undefined\n        ? { maxReadAhead: options.maxReadAhead }\n        : {}),\n      ...(options.onMalformedLine\n        ? { onMalformedLine: options.onMalformedLine }\n        : {}),\n      ...(options.onUnknownEnvelope\n        ? { onUnknownEnvelope: options.onUnknownEnvelope }\n        : {}),\n      ...(options.onValidEnvelope\n        ? { onValidEnvelope: options.onValidEnvelope }\n        : {}),\n    }),\n    response,\n  };\n}\n\nexport interface StreamRequestOptions {\n  method: \"GET\" | \"POST\";\n  body?: unknown;\n  /** Extra wire-semantic headers (`Accept`, `Last-Event-ID`). */\n  headers?: Record<string, string>;\n  signal?: AbortSignal;\n}\n\n/**\n * Execute a streaming request. Throws `MatrxApiError` on a non-2xx response\n * (reading the error body as JSON when possible) or when a 2xx response\n * carries no body; resolves with the validated `Response` otherwise.\n */\nexport async function requestStream(\n  transport: MatrxTransport,\n  path: string,\n  options: StreamRequestOptions,\n): Promise<Response> {\n  const hasBody = options.method !== \"GET\" && options.body !== undefined;\n  const response = await transport.fetch(path, {\n    method: options.method,\n    headers: {\n      ...(hasBody ? { \"Content-Type\": \"application/json\" } : {}),\n      ...options.headers,\n    },\n    ...(hasBody ? { body: JSON.stringify(options.body) } : {}),\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n  if (!response.ok) return throwApiError(path, response);\n  if (!response.body) {\n    throw new MatrxApiError({\n      status: response.status,\n      path,\n      serverDetail: { code: \"missing_response_body\" },\n      message: \"The streaming response carried no body.\",\n    });\n  }\n  return response;\n}\n","// AUTO-GENERATED — do not edit by hand.\n// Source: aidream/services/agent_service/portable.py\n// Run: uv run python scripts/generate_types.py portable-agent\n\nexport const PORTABLE_AGENT_CONTRACT = \"portable-agent.v1\";\n\nexport type JsonValue =\n  | string\n  | number\n  | boolean\n  | null\n  | JsonValue[]\n  | { [key: string]: JsonValue };\n\nexport interface PortableAgentRequest {\n  variables?: Record<string, JsonValue>;\n  surface?: string;\n}\n\nexport interface PortableSkill {\n  id: string;\n  tier: \"included\" | \"listed\";\n  slug: string;\n  label: string;\n  description: string;\n  path: string;\n  content: string;\n  body: string;\n  content_hash: string;\n}\n\nexport interface PortableTool {\n  name: string;\n  canonical_name: string;\n  description: string;\n  parameters: Record<string, JsonValue>;\n}\n\nexport interface PortableUnavailable {\n  kind: \"tool\" | \"skill\" | \"variable\" | \"message\" | \"mcp_server\" | \"tools\";\n  name: string;\n  reason: string;\n}\n\nexport interface PortableAgentBundle {\n  contract: \"portable-agent.v1\";\n  agent_id: string;\n  version_id: string | null;\n  version_number: number | null;\n  is_version: boolean;\n  name: string;\n  definition_hash: string;\n  model_id: string;\n  instructions: string;\n  variables: Record<string, JsonValue>[];\n  filled_variables: string[];\n  skills: PortableSkill[];\n  tools: PortableTool[];\n  surface: string;\n  unavailable: PortableUnavailable[];\n}\n","/**\n * `@ai-matrx/agents/portable` — an AI Matrx agent as pieces a coding CLI loads.\n *\n * `fetchPortableAgent` reads `POST /ai/agents/{id}/portable` (or the version\n * door) and returns the server's `PortableAgentBundle`: the instructions with\n * the person's variable values filled, the skills as Claude `SKILL.md` files,\n * the server tools in MCP shape, and `unavailable[]` — what could not be\n * carried and why. The types are GENERATED from the server's Pydantic models\n * (`types.generated.ts`, `uv run python scripts/generate_types.py portable-agent`\n * in aidream), so the two cannot drift.\n *\n * Pure entry: no React, no Node, no I/O at import. Credentials and the\n * organization travel through the host's `MatrxTransport`\n * (`createMatrxTransport({ credentials, organizationId })`).\n */\n\nimport { encodePathSegment, requestJson } from \"../matrx/internal\";\nimport type { MatrxTransport } from \"../matrx/transport\";\nimport type {\n  JsonValue,\n  PortableAgentBundle,\n  PortableAgentRequest,\n} from \"./types.generated\";\n\nexport * from \"./types.generated\";\n\n/** Which definition to load: the agent's current one, or one immutable version. */\nexport type PortableAgentTarget =\n  | { agentId: string; versionId?: undefined }\n  | { versionId: string; agentId?: string | undefined };\n\nexport interface FetchPortableAgentOptions {\n  /** The person's values, by variable name. Unfilled variables use the agent's defaults. */\n  variables?: Record<string, JsonValue>;\n  /** The `ui.ui_surface` tools resolve on. Default: the server's coding-session surface. */\n  surface?: string;\n  signal?: AbortSignal;\n}\n\n/** The server path for a target — exported so a host's tests can assert it. */\nexport function portableAgentPath(target: PortableAgentTarget): string {\n  return target.versionId\n    ? `/ai/agents/versions/${encodePathSegment(target.versionId)}/portable`\n    : `/ai/agents/${encodePathSegment(target.agentId ?? \"\")}/portable`;\n}\n\n/**\n * Load one agent as a portable bundle. Throws `MatrxApiError` on refusal —\n * 401 signed out, 404 not found or not shared with this person.\n */\nexport function fetchPortableAgent(\n  transport: MatrxTransport,\n  target: PortableAgentTarget,\n  options: FetchPortableAgentOptions = {},\n): Promise<PortableAgentBundle> {\n  const body: PortableAgentRequest = {\n    variables: options.variables ?? {},\n    ...(options.surface ? { surface: options.surface } : {}),\n  };\n  return requestJson<PortableAgentBundle>(transport, portableAgentPath(target), {\n    method: \"POST\",\n    body,\n    ...(options.signal ? { signal: options.signal } : {}),\n  });\n}\n\n/** One saved version of an agent (`AgentVersionInfo` server-side). */\nexport interface PortableAgentVersion {\n  id: string;\n  agent_id: string;\n  version_number: number;\n  name: string;\n  change_note: string | null;\n  changed_at: string | null;\n}\n\n/**\n * The agent's saved versions, oldest first (`GET /agent-service/agents/{id}/versions`,\n * authorized through the same viewer rule as the agent). Feeds a version menu.\n */\nexport function fetchPortableAgentVersions(\n  transport: MatrxTransport,\n  agentId: string,\n  options: { signal?: AbortSignal } = {},\n): Promise<PortableAgentVersion[]> {\n  return requestJson<PortableAgentVersion[]>(\n    transport,\n    `/agent-service/agents/${encodePathSegment(agentId)}/versions`,\n    { method: \"GET\", ...(options.signal ? { signal: options.signal } : {}) },\n  );\n}\n\n/** What a bundle loaded, counted — what a header chip shows. */\nexport interface PortableAgentLoadSummary {\n  instructions: boolean;\n  skills: { loaded: number; total: number };\n  tools: { loaded: number; total: number };\n}\n\n/** Count what a bundle carries against what the agent declares. */\nexport function summarizePortableAgent(bundle: PortableAgentBundle): PortableAgentLoadSummary {\n  const missingSkills = bundle.unavailable.filter((u) => u.kind === \"skill\").length;\n  const missingTools = bundle.unavailable.filter((u) => u.kind === \"tool\").length;\n  return {\n    instructions: bundle.instructions.trim().length > 0,\n    skills: { loaded: bundle.skills.length, total: bundle.skills.length + missingSkills },\n    tools: { loaded: bundle.tools.length, total: bundle.tools.length + missingTools },\n  };\n}\n"],"mappings":"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","names":[]}