@finalai/agent-provider 0.1.0

package/dist/modules/harness.mjs

@@ -0,0 +1,213 @@
+import * as z from "zod";
+import { CredentialRoute, routeGrantSchema } from "./credential-routes.mjs";
+import { CredentialDelivery, InferenceCredentialKind } from "./credentials.mjs";
+import { jsonObjectSchema, jsonSchemaSchema } from "./json.mjs";
+import { BaseCapability, InstructionRole } from "./manifest.mjs";
+import { bundleRef, providerRefSchema } from "./provider-ref.mjs";
+import { referencedSharedSchemas, SCHEMA_IDS } from "./schemas.mjs";
+const PENDING_BUNDLE_EXPORT = "<pending>";
+var AcpTransport = /* @__PURE__ */ ((AcpTransport2) => {
+  AcpTransport2["Relay"] = "relay";
+  AcpTransport2["Ws"] = "ws";
+  AcpTransport2["Http"] = "http";
+  AcpTransport2["Stdio"] = "stdio";
+  return AcpTransport2;
+})(AcpTransport || {});
+var McpTransportKind = /* @__PURE__ */ ((McpTransportKind2) => {
+  McpTransportKind2["Acp"] = "acp";
+  McpTransportKind2["Http"] = "http";
+  McpTransportKind2["Stdio"] = "stdio";
+  return McpTransportKind2;
+})(McpTransportKind || {});
+var BaseToolProvision = /* @__PURE__ */ ((BaseToolProvision2) => {
+  BaseToolProvision2["Bound"] = "bound";
+  BaseToolProvision2["HostDisableable"] = "host-disableable";
+  BaseToolProvision2["HostFixed"] = "host-fixed";
+  return BaseToolProvision2;
+})(BaseToolProvision || {});
+var SandboxWire = /* @__PURE__ */ ((SandboxWire2) => {
+  SandboxWire2["HandleRpc"] = "handle-rpc";
+  SandboxWire2["Mcp"] = "mcp";
+  return SandboxWire2;
+})(SandboxWire || {});
+var UserInstructionDelivery = /* @__PURE__ */ ((UserInstructionDelivery2) => {
+  UserInstructionDelivery2["History"] = "history";
+  UserInstructionDelivery2["System"] = "system";
+  return UserInstructionDelivery2;
+})(UserInstructionDelivery || {});
+var HarnessTrustClass = /* @__PURE__ */ ((HarnessTrustClass2) => {
+  HarnessTrustClass2["FirstParty"] = "first-party";
+  HarnessTrustClass2["ThirdParty"] = "third-party";
+  return HarnessTrustClass2;
+})(HarnessTrustClass || {});
+var PromptWhileRunning = /* @__PURE__ */ ((PromptWhileRunning2) => {
+  PromptWhileRunning2["Inject"] = "inject";
+  PromptWhileRunning2["Queue"] = "queue";
+  return PromptWhileRunning2;
+})(PromptWhileRunning || {});
+const DEFAULT_PROMPT_WHILE_RUNNING = "queue" /* Queue */;
+const DEFAULT_SESSION_SURVIVES_DISCONNECT = false;
+const baseToolDeclarationSchema = z.object({
+  provision: z.nativeEnum(BaseToolProvision),
+  nativeTools: z.array(z.string())
+});
+const harnessDescriptionSchema = z.object({
+  // Everything configurable about this harness (model, reasoning, credentials,
+  // permission mode, instructions, skills, cwd, ...). JSON Schema so Build can
+  // render it; may $ref the shared final://schemas/* fragments.
+  configSchema: jsonSchemaSchema,
+  // Absent: user fragments enter history. System-only programs declare their conversion.
+  userInstructionDelivery: z.nativeEnum(UserInstructionDelivery).optional(),
+  acp: z.object({
+    transports: z.array(z.nativeEnum(AcpTransport)).min(1),
+    mcp: z.array(z.nativeEnum(McpTransportKind))
+  }),
+  // A capability missing here is unavailable on this harness.
+  baseTools: z.partialRecord(z.nativeEnum(BaseCapability), baseToolDeclarationSchema),
+  consumes: z.array(z.nativeEnum(SandboxWire)),
+  inference: z.object({
+    vendors: z.array(z.string()),
+    kinds: z.array(z.nativeEnum(InferenceCredentialKind)),
+    delivery: z.nativeEnum(CredentialDelivery)
+  }),
+  // Absent: third-party.
+  trust: z.nativeEnum(HarnessTrustClass).optional(),
+  supports: z.object({
+    observe: z.boolean(),
+    resumeReplay: z.boolean(),
+    fork: z.boolean(),
+    // Renders _meta["final.ai"].author itself; otherwise the channel prepends
+    // the author's name to the text.
+    authorMeta: z.boolean(),
+    // Explicit false: native toolPolicy cannot be enforced by this adapter's public surface.
+    nativeToolPolicy: z.boolean().optional()
+  }),
+  promptWhileRunning: z.nativeEnum(PromptWhileRunning).default(DEFAULT_PROMPT_WHILE_RUNNING),
+  // Keeps the session, its running work and its open requests across a dropped
+  // connection, buffers updates for replay, and re-raises the open requests
+  // with the same JSON-RPC ids on the next session/resume. False:
+  // open turns end `harness_state_lost` after a reconnect.
+  sessionSurvivesDisconnect: z.boolean().default(DEFAULT_SESSION_SURVIVES_DISCONNECT)
+});
+const deliveredHarnessConfig = (args) => {
+  if (args.description.userInstructionDelivery !== "system" /* System */)
+    return args.config;
+  const config = jsonObjectSchema.safeParse(args.config);
+  if (!config.success) return args.config;
+  const fields = referencedSharedSchemas(args.description.configSchema);
+  const field = Object.entries(fields).find(([, schema]) => schema === SCHEMA_IDS.instructions)?.[0] ?? "instructions";
+  const instructions = config.data[field];
+  if (!Array.isArray(instructions)) return args.config;
+  return {
+    ...config.data,
+    [field]: instructions.map((value) => {
+      const fragment = jsonObjectSchema.safeParse(value);
+      return fragment.success && fragment.data["role"] === InstructionRole.User ? { ...fragment.data, role: InstructionRole.System } : value;
+    })
+  };
+};
+const harnessSessionRefSchema = z.object({
+  harness: providerRefSchema,
+  // Opaque to the session service; the harness's own id for the session.
+  harnessSessionRef: z.string().min(1),
+  // Bumped whenever the harness loses state; a mismatch on resume means the
+  // session service must re-seed with session/new.
+  generation: z.number().int().nonnegative()
+});
+import {
+  credentialRefreshRequestSchema,
+  CredentialRoute as CredentialRoute2,
+  routeGrantSchema as routeGrantSchema2
+} from "./credential-routes.mjs";
+const atOpenModelCredentialSchema = z.object({
+  vendor: z.string(),
+  kind: z.nativeEnum(InferenceCredentialKind),
+  baseUrl: z.string().min(1).nullable(),
+  apiKey: z.string().min(1).nullable(),
+  subscription: z.object({
+    format: z.union([z.literal("claude-setup-token"), z.literal("chatgpt-auth-tokens")]),
+    value: z.string().min(1)
+  }).nullable(),
+  fingerprint: z.string()
+});
+const credentialGrantRefreshSchema = z.object({
+  url: z.string().min(1),
+  token: z.string().min(1),
+  harnessSessionId: z.string().min(1),
+  expiresAt: z.string()
+});
+const credentialGrantSchema = z.object({
+  brokerUrl: z.string().min(1),
+  grants: z.array(routeGrantSchema),
+  atOpen: atOpenModelCredentialSchema.nullable(),
+  refresh: credentialGrantRefreshSchema.nullable()
+});
+const endpointTokenSchema = z.object({
+  url: z.string().min(1),
+  token: z.string(),
+  expiresAt: z.string()
+});
+const sandboxTargetEndpointSchema = z.object({
+  target: z.string().min(1),
+  bindingId: z.string().min(1),
+  capabilities: z.array(z.string()),
+  rpc: endpointTokenSchema.nullable(),
+  mcp: endpointTokenSchema.nullable()
+});
+const renewedMcpServerSchema = z.object({
+  name: z.string().min(1),
+  url: z.string().min(1),
+  headers: z.array(z.object({ name: z.string().min(1), value: z.string() }))
+});
+const credentialRefreshResultSchema = credentialGrantSchema.extend({
+  mcpServers: z.array(renewedMcpServerSchema).default([]),
+  sandboxes: z.record(z.string(), sandboxTargetEndpointSchema).default({})
+});
+const grantRefreshFor = (args) => {
+  const grant = args.grants.find((candidate) => candidate.route === CredentialRoute.Model) ?? args.grants[0];
+  if (grant == null) return null;
+  return {
+    url: `${args.brokerUrl.replace(/\/+$/, "")}/refresh`,
+    token: grant.token,
+    harnessSessionId: args.harnessSessionId,
+    expiresAt: grant.expiresAt
+  };
+};
+const defineHarness = (implementation) => {
+  const binding = (config) => ({
+    harness: bundleRef(PENDING_BUNDLE_EXPORT),
+    config,
+    definedHarness: true
+  });
+  return Object.assign(binding, implementation);
+};
+const describeConfigSchema = (description) => description.configSchema;
+export {
+  AcpTransport,
+  BaseToolProvision,
+  CredentialRoute2 as CredentialRoute,
+  DEFAULT_PROMPT_WHILE_RUNNING,
+  DEFAULT_SESSION_SURVIVES_DISCONNECT,
+  HarnessTrustClass,
+  McpTransportKind,
+  PENDING_BUNDLE_EXPORT,
+  PromptWhileRunning,
+  SandboxWire,
+  UserInstructionDelivery,
+  atOpenModelCredentialSchema,
+  baseToolDeclarationSchema,
+  credentialGrantRefreshSchema,
+  credentialGrantSchema,
+  credentialRefreshRequestSchema,
+  credentialRefreshResultSchema,
+  defineHarness,
+  deliveredHarnessConfig,
+  describeConfigSchema,
+  grantRefreshFor,
+  harnessDescriptionSchema,
+  harnessSessionRefSchema,
+  renewedMcpServerSchema,
+  routeGrantSchema2 as routeGrantSchema,
+  sandboxTargetEndpointSchema
+};
+//# sourceMappingURL=harness.mjs.map

package/dist/modules/harness.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/harness.ts"],
+  "sourcesContent": ["import type { McpServer } from '@agentclientprotocol/sdk/experimental/v2';\nimport * as z from 'zod';\nimport { CredentialRoute, routeGrantSchema, type RouteGrantIface } from \"./credential-routes.mjs\";\nimport { CredentialDelivery, InferenceCredentialKind } from \"./credentials.mjs\";\nimport type { JsonSchema, JsonValue } from \"./json.mjs\";\nimport { jsonObjectSchema, jsonSchemaSchema } from \"./json.mjs\";\nimport { BaseCapability, InstructionRole, type ResolvedAgentManifestIface } from \"./manifest.mjs\";\nimport { bundleRef, providerRefSchema, type ProviderRef } from \"./provider-ref.mjs\";\nimport { referencedSharedSchemas, SCHEMA_IDS } from \"./schemas.mjs\";\n\n// Placeholder export name the compiler replaces with the defining module's path.\nexport const PENDING_BUNDLE_EXPORT = '<pending>';\n\n// A harness is a specific ACP agent program together with how to reach it. Hosting is part of what a harness is, so there is no\n// engine parameter: \"Pi on Final's serverless runtime\" and \"Pi on a server you\n// run\" are two harnesses. The hosting half is deliberately small; everything\n// about what the agent does goes over ACP v2.\n\nexport enum AcpTransport {\n  Relay = 'relay',\n  Ws = 'ws',\n  Http = 'http',\n  Stdio = 'stdio',\n}\n\nexport enum McpTransportKind {\n  Acp = 'acp',\n  Http = 'http',\n  Stdio = 'stdio',\n}\n\n// How a harness provides one base capability.\nexport enum BaseToolProvision {\n  // Routed to the declared sandbox target.\n  Bound = 'bound',\n  // Native on the harness's host and switchable through its own allow-lists.\n  HostDisableable = 'host-disableable',\n  // Native on the harness's host and not switchable.\n  HostFixed = 'host-fixed',\n}\n\n// SDK wires a harness speaks to reach a bound sandbox target.\nexport enum SandboxWire {\n  HandleRpc = 'handle-rpc',\n  Mcp = 'mcp',\n}\n\nexport enum UserInstructionDelivery {\n  History = 'history',\n  System = 'system',\n}\n\n// Who operates the place a harness's credentials land. Every\n// harness, Final's included, gets the same grant forms; a subscription goes to\n// a third-party harness only when its owner allowed third-party harnesses.\n// Only installed provider packages may declare first-party; a bundle-declared\n// harness is third-party whatever it declares.\nexport enum HarnessTrustClass {\n  // The provider operates the harness on infrastructure it runs (Final's serverless harnesses).\n  FirstParty = 'first-party',\n  // Someone else's host or program (remote hosts, external ACP agents, local processes).\n  ThirdParty = 'third-party',\n}\n\n// What an accepted session/prompt does while the session is running. Both are valid; refusing one is a conformance failure.\nexport enum PromptWhileRunning {\n  // Joins the running work: the model sees it at its next step.\n  Inject = 'inject',\n  // Runs after the current work goes idle; dropped by session/cancel if not started.\n  Queue = 'queue',\n}\n\n// Defaults for a description that does not declare the hosting contract's\n// newer fields (bundle harnesses, older registrations): the session service\n// then assumes nothing survives a dropped connection and that a prompt while\n// running waits for idle.\nexport const DEFAULT_PROMPT_WHILE_RUNNING = PromptWhileRunning.Queue;\nexport const DEFAULT_SESSION_SURVIVES_DISCONNECT = false;\n\nexport const baseToolDeclarationSchema = z.object({\n  provision: z.nativeEnum(BaseToolProvision),\n  nativeTools: z.array(z.string()),\n});\n\nexport const harnessDescriptionSchema = z.object({\n  // Everything configurable about this harness (model, reasoning, credentials,\n  // permission mode, instructions, skills, cwd, ...). JSON Schema so Build can\n  // render it; may $ref the shared final://schemas/* fragments.\n  configSchema: jsonSchemaSchema,\n  // Absent: user fragments enter history. System-only programs declare their conversion.\n  userInstructionDelivery: z.nativeEnum(UserInstructionDelivery).optional(),\n  acp: z.object({\n    transports: z.array(z.nativeEnum(AcpTransport)).min(1),\n    mcp: z.array(z.nativeEnum(McpTransportKind)),\n  }),\n  // A capability missing here is unavailable on this harness.\n  baseTools: z.partialRecord(z.nativeEnum(BaseCapability), baseToolDeclarationSchema),\n  consumes: z.array(z.nativeEnum(SandboxWire)),\n  inference: z.object({\n    vendors: z.array(z.string()),\n    kinds: z.array(z.nativeEnum(InferenceCredentialKind)),\n    delivery: z.nativeEnum(CredentialDelivery),\n  }),\n  // Absent: third-party.\n  trust: z.nativeEnum(HarnessTrustClass).optional(),\n  supports: z.object({\n    observe: z.boolean(),\n    resumeReplay: z.boolean(),\n    fork: z.boolean(),\n    // Renders _meta[\"final.ai\"].author itself; otherwise the channel prepends\n    // the author's name to the text.\n    authorMeta: z.boolean(),\n    // Explicit false: native toolPolicy cannot be enforced by this adapter's public surface.\n    nativeToolPolicy: z.boolean().optional(),\n  }),\n  promptWhileRunning: z.nativeEnum(PromptWhileRunning).default(DEFAULT_PROMPT_WHILE_RUNNING),\n  // Keeps the session, its running work and its open requests across a dropped\n  // connection, buffers updates for replay, and re-raises the open requests\n  // with the same JSON-RPC ids on the next session/resume. False:\n  // open turns end `harness_state_lost` after a reconnect.\n  sessionSurvivesDisconnect: z.boolean().default(DEFAULT_SESSION_SURVIVES_DISCONNECT),\n});\n\nexport type BaseToolDeclarationIface = z.infer<typeof baseToolDeclarationSchema>;\nexport type HarnessDescriptionIface = z.infer<typeof harnessDescriptionSchema>;\n\nexport const deliveredHarnessConfig = (args: {\n  config: JsonValue;\n  description: HarnessDescriptionIface;\n}): JsonValue => {\n  if (args.description.userInstructionDelivery !== UserInstructionDelivery.System)\n    return args.config;\n  const config = jsonObjectSchema.safeParse(args.config);\n  if (!config.success) return args.config;\n  const fields = referencedSharedSchemas(args.description.configSchema);\n  const field =\n    Object.entries(fields).find(([, schema]) => schema === SCHEMA_IDS.instructions)?.[0] ??\n    'instructions';\n  const instructions = config.data[field];\n  if (!Array.isArray(instructions)) return args.config;\n  return {\n    ...config.data,\n    [field]: instructions.map((value) => {\n      const fragment = jsonObjectSchema.safeParse(value);\n      return fragment.success && fragment.data['role'] === InstructionRole.User\n        ? { ...fragment.data, role: InstructionRole.System }\n        : value;\n    }),\n  };\n};\n\nexport const harnessSessionRefSchema = z.object({\n  harness: providerRefSchema,\n  // Opaque to the session service; the harness's own id for the session.\n  harnessSessionRef: z.string().min(1),\n  // Bumped whenever the harness loses state; a mismatch on resume means the\n  // session service must re-seed with session/new.\n  generation: z.number().int().nonnegative(),\n});\n\nexport type HarnessSessionRefIface = z.infer<typeof harnessSessionRefSchema>;\n\n// Route-scoped, short-lived grants: credential-routes.ts.\nexport {\n  credentialRefreshRequestSchema,\n  CredentialRoute,\n  routeGrantSchema,\n  type CredentialRefreshRequestIface,\n  type RouteGrantIface,\n} from \"./credential-routes.mjs\";\n\nexport interface CredentialGrantIface {\n  // Base URL of the broker routes (`<base>/model`, `<base>/refresh`, ...).\n  brokerUrl: string;\n  grants: RouteGrantIface[];\n  // What the model grant resolved to, for harnesses that hand credentials over\n  // at open (delivery 'at-open'). Null for per-request harnesses.\n  atOpen: AtOpenModelCredentialIface | null;\n  // How to renew this grant; null only when it carries no route grant.\n  refresh: CredentialGrantRefreshIface | null;\n}\n\n// Renewal is pulled, never pushed. Per-request harnesses fetch\n// `<brokerUrl>/model` on every request. At-open harnesses (or their host)\n// POST `url` with `authorization: Bearer <token>` and a\n// `credentialRefreshRequestSchema` body before `expiresAt` and once after a\n// vendor 401; the answer is the grant's next generation (a\n// `credentialRefreshResultSchema` body with its own `refresh`), which replaces\n// this one. The broker resolves the policy again for it, so a disconnected\n// credential falls through; a revoked grant (every open revokes the previous\n// open's grants) or a closed harness session is refused (401).\nexport interface CredentialGrantRefreshIface {\n  // `<brokerUrl>/refresh`.\n  url: string;\n  // One of this grant's own route grants (the model route's).\n  token: string;\n  harnessSessionId: string;\n  // When `token` expires; a refresh after it is refused.\n  expiresAt: string;\n}\n\nexport interface AtOpenModelCredentialIface {\n  vendor: string;\n  kind: InferenceCredentialKind;\n  // Base URL and bearer for an OpenAI- or Anthropic-compatible endpoint (the\n  // platform proxy, a corporate gateway) or the vendor itself.\n  baseUrl: string | null;\n  apiKey: string | null;\n  // Subscription material for Final-managed harnesses only (Claude setup token,\n  // Codex app-server chatgptAuthTokens); renewed through the grant's refresh route.\n  subscription: { format: 'claude-setup-token' | 'chatgpt-auth-tokens'; value: string } | null;\n  fingerprint: string;\n}\n\nexport const atOpenModelCredentialSchema = z.object({\n  vendor: z.string(),\n  kind: z.nativeEnum(InferenceCredentialKind),\n  baseUrl: z.string().min(1).nullable(),\n  apiKey: z.string().min(1).nullable(),\n  subscription: z\n    .object({\n      format: z.union([z.literal('claude-setup-token'), z.literal('chatgpt-auth-tokens')]),\n      value: z.string().min(1),\n    })\n    .nullable(),\n  fingerprint: z.string(),\n}) satisfies z.ZodType<AtOpenModelCredentialIface>;\n\nexport const credentialGrantRefreshSchema = z.object({\n  url: z.string().min(1),\n  token: z.string().min(1),\n  harnessSessionId: z.string().min(1),\n  expiresAt: z.string(),\n}) satisfies z.ZodType<CredentialGrantRefreshIface>;\n\nexport const credentialGrantSchema = z.object({\n  brokerUrl: z.string().min(1),\n  grants: z.array(routeGrantSchema),\n  atOpen: atOpenModelCredentialSchema.nullable(),\n  refresh: credentialGrantRefreshSchema.nullable(),\n}) satisfies z.ZodType<CredentialGrantIface>;\n\n// An `http` MCP server entry the harness was handed in `session/new`\n// (`mcpServers`), with fresh headers. Same name and url; the harness swaps the\n// headers of the entry with that url.\nexport interface RenewedMcpServerIface {\n  name: string;\n  url: string;\n  headers: { name: string; value: string }[];\n}\n\n// What a refresh answers: the grant's next generation, plus fresh copies of the\n// other short-lived material the harness was handed at open. Renewing the\n// `mcp` route renews the session's `http` MCP server headers; renewing\n// `sandbox` renews the bound sandbox targets' endpoint tokens.\nexport interface CredentialRefreshResultIface extends CredentialGrantIface {\n  mcpServers: RenewedMcpServerIface[];\n  sandboxes: Record<string, SandboxTargetEndpointIface>;\n}\n\nconst endpointTokenSchema = z.object({\n  url: z.string().min(1),\n  token: z.string(),\n  expiresAt: z.string(),\n});\n\nexport const sandboxTargetEndpointSchema = z.object({\n  target: z.string().min(1),\n  bindingId: z.string().min(1),\n  capabilities: z.array(z.string()),\n  rpc: endpointTokenSchema.nullable(),\n  mcp: endpointTokenSchema.nullable(),\n}) satisfies z.ZodType<SandboxTargetEndpointIface>;\n\nexport const renewedMcpServerSchema = z.object({\n  name: z.string().min(1),\n  url: z.string().min(1),\n  headers: z.array(z.object({ name: z.string().min(1), value: z.string() })),\n}) satisfies z.ZodType<RenewedMcpServerIface>;\n\n// Absent renewals parse as none, so an answer without them still parses.\nexport const credentialRefreshResultSchema = credentialGrantSchema.extend({\n  mcpServers: z.array(renewedMcpServerSchema).default([]),\n  sandboxes: z.record(z.string(), sandboxTargetEndpointSchema).default({}),\n}) satisfies z.ZodType<CredentialRefreshResultIface, unknown>;\n\n// The refresh descriptor for a set of route grants: authenticated by the model\n// grant (else the first), due when that token expires.\nexport const grantRefreshFor = (args: {\n  brokerUrl: string;\n  harnessSessionId: string;\n  grants: readonly RouteGrantIface[];\n}): CredentialGrantRefreshIface | null => {\n  const grant =\n    args.grants.find((candidate) => candidate.route === CredentialRoute.Model) ?? args.grants[0];\n  if (grant == null) return null;\n  return {\n    url: `${args.brokerUrl.replace(/\\/+$/, '')}/refresh`,\n    token: grant.token,\n    harnessSessionId: args.harnessSessionId,\n    expiresAt: grant.expiresAt,\n  };\n};\n\nexport interface SecretReaderIface {\n  get(name: string): Promise<string | null>;\n}\n\nexport interface TraceContextIface {\n  traceparent: string | null;\n  tracestate: string | null;\n}\n\n// A bound sandbox target as the session service hands it to a harness: a stable\n// per-binding address that starts the sandbox on the first tool call. Never a lease, a data-plane token for a live VM, or provider code.\nexport interface SandboxTargetEndpointIface {\n  target: string;\n  bindingId: string;\n  capabilities: string[];\n  rpc: { url: string; token: string; expiresAt: string } | null;\n  mcp: { url: string; token: string; expiresAt: string } | null;\n}\n\nexport interface HarnessSessionContextIface {\n  sessionId: string;\n  organizationId: string;\n  definitionId: string;\n  revisionId: string;\n  // Public base URL of the session service for this session (MCP over HTTP,\n  // sandbox endpoints, the broker).\n  sessionServiceUrl: string;\n  // The region of the session service serving the session and its sandbox\n  // bindings, so a harness can run near it; null when unknown.\n  sessionServiceRegion?: string | null;\n}\n\n// Lifecycle signals a harness implementation may report about the runtime\n// hosting a session (invocations, metering, traces). Informational: the\n// session service records them (agent.harness_invocations, Tinybird) and never\n// depends on them for correctness.\nexport interface HarnessObserverIface {\n  // The runtime accepted the invocation request (its response began).\n  invocationAccepted?(event: { invocationRef: string; at: string }): void;\n  invocationStarted?(event: {\n    invocationRef: string;\n    at: string;\n    bootMs: number | null;\n    // The runtime's deployed version (Workers version id, commit), for rollouts.\n    versionId?: string | null;\n    commitSha?: string | null;\n  }): void;\n  invocationKeepalive?(event: { invocationRef: string; at: string; activeWork: number }): void;\n  invocationEnded?(event: {\n    invocationRef: string;\n    at: string;\n    reason: string;\n    error: string | null;\n    metering: Record<string, number>;\n  }): void;\n  trace?(event: { name: string; at: string; fields: Record<string, JsonValue> }): void;\n}\n\nexport interface OpenHarnessSessionArgsIface {\n  session: HarnessSessionContextIface;\n  // The session service's id for this harness session (agent.harness_sessions);\n  // implementations key their runtime state and route grants by it.\n  harnessSessionId: string;\n  // Hosting may authorize the child endpoint to fork this source through ACP.\n  forkSource?: { ref: HarnessSessionRefIface; acpSessionId: string };\n  observer?: HarnessObserverIface;\n  // The binding's config, validated against configSchema, dynamic slots resolved.\n  config: JsonValue;\n  manifest: ResolvedAgentManifestIface;\n  // Already materialized ACP MCP server entries: authored tools, connections\n  // (Final's MCP server among them), sandbox MCP projections where applicable.\n  mcpServers: McpServer[];\n  // Declared base capabilities with the target endpoint each is bound to.\n  baseTools: Partial<Record<BaseCapability, SandboxTargetEndpointIface>>;\n  sandboxes: Record<string, SandboxTargetEndpointIface>;\n  credentials: CredentialGrantIface;\n  secrets: SecretReaderIface;\n  trace: TraceContextIface;\n}\n\nexport interface ResumeHarnessSessionArgsIface extends OpenHarnessSessionArgsIface {\n  ref: HarnessSessionRefIface;\n  // Last log seq the session service holds from this harness session; the\n  // harness replays anything newer after session/resume.\n  lastSeq: number;\n}\n\n// Resolved only in memory; refs/manifests retain secret names, never TLS keys.\nexport interface HarnessClientTlsIface {\n  cert: string;\n  key: string;\n  ca?: string;\n}\n\nexport type HarnessEndpointIface =\n  | {\n      ref: HarnessSessionRefIface;\n      transport: AcpTransport.Ws;\n      url: string;\n      headers: Record<string, string>;\n      resolveHeaders?: () => Promise<Record<string, string>>;\n      tls?: HarnessClientTlsIface;\n    }\n  | {\n      ref: HarnessSessionRefIface;\n      transport: AcpTransport.Http;\n      url: string;\n      headers: Record<string, string>;\n      resolveHeaders?: () => Promise<Record<string, string>>;\n      tls?: HarnessClientTlsIface;\n    }\n  // websocket-gateway relay channel (Final-managed harnesses).\n  | { ref: HarnessSessionRefIface; transport: AcpTransport.Relay; channel: string; token: string }\n  // Local development, CI and conformance only.\n  | {\n      ref: HarnessSessionRefIface;\n      transport: AcpTransport.Stdio;\n      command: string;\n      args: string[];\n      env: Record<string, string>;\n    };\n\nexport interface HarnessHealthIface {\n  ok: boolean;\n  detail?: string;\n  checkedAt: string;\n}\n\n// The binding a description is asked for: its config (validated against the\n// configSchema of the binding-free description) and the definition's secrets.\nexport interface DescribeHarnessArgsIface {\n  config: JsonValue;\n  secrets: SecretReaderIface;\n}\n\nexport interface HarnessIface {\n  // Without a binding: what Build renders before one exists (configSchema,\n  // declared capabilities). With one: the description of that binding, which a\n  // harness reaching an arbitrary agent derives from the agent itself (e.g. its\n  // `initialize`). Every harness implements both; most ignore the binding.\n  describe(binding?: DescribeHarnessArgsIface): Promise<HarnessDescriptionIface>;\n  open(args: OpenHarnessSessionArgsIface): Promise<HarnessEndpointIface>;\n  resume(args: ResumeHarnessSessionArgsIface): Promise<HarnessEndpointIface>;\n  park(ref: HarnessSessionRefIface): Promise<void>;\n  // Graceful by default: the program's state is durable (resumable) before it\n  // stops, bounded by the implementation's timeout, then forced. `force` skips\n  // the wait; the session service passes it when the program did not settle\n  // ACP `session/close` within its bound.\n  close(ref: HarnessSessionRefIface, opts?: CloseHarnessSessionOptsIface): Promise<void>;\n  health(\n    ref: HarnessSessionRefIface,\n    context?: DescribeHarnessArgsIface,\n  ): Promise<HarnessHealthIface>;\n}\n\nexport interface CloseHarnessSessionOptsIface {\n  force?: boolean;\n  // As with health, retained refs can resolve current client TLS without storing keys in the ref.\n  context?: DescribeHarnessArgsIface;\n}\n\n// What an installed harness module exports: the implementation plus an\n// authoring helper that builds the manifest binding.\nexport interface HarnessModuleIface<Config> {\n  ref: ProviderRef;\n  harness: HarnessIface;\n  binding: (config: Config) => { harness: ProviderRef; config: JsonValue };\n}\n\n// Custom harnesses in a definition's bundle. Calling the result\n// with a config yields the manifest binding; the implementation is resolved\n// from the bundle by export name.\nexport interface DefinedHarnessBindingIface {\n  harness: ProviderRef;\n  config: JsonValue;\n  definedHarness: true;\n}\n\nexport interface DefinedHarnessIface<Config> extends HarnessIface {\n  (config: Config): DefinedHarnessBindingIface;\n}\n\nexport const defineHarness = <Config extends JsonValue = JsonValue>(\n  implementation: HarnessIface,\n): DefinedHarnessIface<Config> => {\n  // The export name is unknown here; the compiler rewrites `bundle:<pending>`\n  // to the module path that exported this harness.\n  const binding = (config: Config): DefinedHarnessBindingIface => ({\n    harness: bundleRef(PENDING_BUNDLE_EXPORT),\n    config,\n    definedHarness: true,\n  });\n  return Object.assign(binding, implementation);\n};\n\nexport const describeConfigSchema = (description: HarnessDescriptionIface): JsonSchema =>\n  description.configSchema;\n"],
+  "mappings": "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",
+  "names": ["AcpTransport", "McpTransportKind", "BaseToolProvision", "SandboxWire", "UserInstructionDelivery", "HarnessTrustClass", "PromptWhileRunning", "CredentialRoute", "routeGrantSchema"]
+}

package/dist/modules/index.d.mts

@@ -0,0 +1,15 @@
+export { ProcessInspectionOperation, inspectedProcessSchema, processInspectionDetailSchema, processInspectionPageSchema, processInspectionRequestSchema, processInspectionResultSchema, type InspectedProcessIface, type ProcessInspectionDetailIface, type ProcessInspectionPageIface, type ProcessInspectionRequestIface, type ProcessInspectionResultIface, } from '@finalai/agent-protocol/process-inspection';
+export * from "./channel.mjs";
+export * from "./credentials.mjs";
+export * from "./dynamic.mjs";
+export * from "./harness.mjs";
+export * from "./json.mjs";
+export * from "./manifest.mjs";
+export * from "./provider-ref.mjs";
+export * from "./sandbox/open-scope.mjs";
+export * from "./sandbox/types.mjs";
+export * from "./schemas.mjs";
+export * from "./channel-context.mjs";
+export * from "./semantic-events.mjs";
+export * from "./sandbox/snapshots.mjs";
+export { SandboxEditorOperation, sandboxEditorRequestSchema, sandboxEditorResultSchema, sandboxEditorSessionSchema, type SandboxEditorRequestIface, type SandboxEditorResultIface, type SandboxEditorSessionIface, } from "./sandbox/editor.mjs";

package/dist/modules/index.mjs

@@ -0,0 +1,40 @@
+import {
+  ProcessInspectionOperation,
+  inspectedProcessSchema,
+  processInspectionDetailSchema,
+  processInspectionPageSchema,
+  processInspectionRequestSchema,
+  processInspectionResultSchema
+} from "@finalai/agent-protocol/process-inspection";
+export * from "./channel.mjs";
+export * from "./credentials.mjs";
+export * from "./dynamic.mjs";
+export * from "./harness.mjs";
+export * from "./json.mjs";
+export * from "./manifest.mjs";
+export * from "./provider-ref.mjs";
+export * from "./sandbox/open-scope.mjs";
+export * from "./sandbox/types.mjs";
+export * from "./schemas.mjs";
+export * from "./channel-context.mjs";
+export * from "./semantic-events.mjs";
+export * from "./sandbox/snapshots.mjs";
+import {
+  SandboxEditorOperation,
+  sandboxEditorRequestSchema,
+  sandboxEditorResultSchema,
+  sandboxEditorSessionSchema
+} from "./sandbox/editor.mjs";
+export {
+  ProcessInspectionOperation,
+  SandboxEditorOperation,
+  inspectedProcessSchema,
+  processInspectionDetailSchema,
+  processInspectionPageSchema,
+  processInspectionRequestSchema,
+  processInspectionResultSchema,
+  sandboxEditorRequestSchema,
+  sandboxEditorResultSchema,
+  sandboxEditorSessionSchema
+};
+//# sourceMappingURL=index.mjs.map

package/dist/modules/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/index.ts"],
+  "sourcesContent": ["export {\n  ProcessInspectionOperation,\n  inspectedProcessSchema,\n  processInspectionDetailSchema,\n  processInspectionPageSchema,\n  processInspectionRequestSchema,\n  processInspectionResultSchema,\n  type InspectedProcessIface,\n  type ProcessInspectionDetailIface,\n  type ProcessInspectionPageIface,\n  type ProcessInspectionRequestIface,\n  type ProcessInspectionResultIface,\n} from '@finalai/agent-protocol/process-inspection';\nexport * from \"./channel.mjs\";\nexport * from \"./credentials.mjs\";\nexport * from \"./dynamic.mjs\";\nexport * from \"./harness.mjs\";\nexport * from \"./json.mjs\";\nexport * from \"./manifest.mjs\";\nexport * from \"./provider-ref.mjs\";\nexport * from \"./sandbox/open-scope.mjs\";\nexport * from \"./sandbox/types.mjs\";\nexport * from \"./schemas.mjs\";\n\nexport * from \"./channel-context.mjs\";\n\nexport * from \"./semantic-events.mjs\";\n\nexport * from \"./sandbox/snapshots.mjs\";\n\nexport {\n  SandboxEditorOperation,\n  sandboxEditorRequestSchema,\n  sandboxEditorResultSchema,\n  sandboxEditorSessionSchema,\n  type SandboxEditorRequestIface,\n  type SandboxEditorResultIface,\n  type SandboxEditorSessionIface,\n} from \"./sandbox/editor.mjs\";\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AACP,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AAEd,cAAc;AAEd,cAAc;AAEd,cAAc;AAEd;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;",
+  "names": []
+}

package/dist/modules/json.d.mts

@@ -0,0 +1,12 @@
+import * as z from 'zod';
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export declare const jsonValueSchema: z.ZodType<JsonValue>;
+export declare const jsonObjectSchema: z.ZodType<JsonObject>;
+export type JsonSchema = JsonObject;
+export declare const jsonSchemaSchema: z.ZodType<JsonSchema>;

package/dist/modules/json.mjs

@@ -0,0 +1,19 @@
+import * as z from "zod";
+const jsonValueSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema)
+  ])
+);
+const jsonObjectSchema = z.record(z.string(), jsonValueSchema);
+const jsonSchemaSchema = jsonObjectSchema;
+export {
+  jsonObjectSchema,
+  jsonSchemaSchema,
+  jsonValueSchema
+};
+//# sourceMappingURL=json.mjs.map

package/dist/modules/json.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/json.ts"],
+  "sourcesContent": ["import * as z from 'zod';\n\nexport type JsonPrimitive = string | number | boolean | null;\nexport type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };\nexport type JsonObject = { [key: string]: JsonValue };\n\nexport const jsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>\n  z.union([\n    z.string(),\n    z.number(),\n    z.boolean(),\n    z.null(),\n    z.array(jsonValueSchema),\n    z.record(z.string(), jsonValueSchema),\n  ]),\n);\n\nexport const jsonObjectSchema: z.ZodType<JsonObject> = z.record(z.string(), jsonValueSchema);\n\n// A JSON Schema document (draft 2020-12). Harness config schemas, tool input\n// schemas and channel config schemas are all JSON Schema so Build can render\n// them without running provider code.\nexport type JsonSchema = JsonObject;\nexport const jsonSchemaSchema: z.ZodType<JsonSchema> = jsonObjectSchema;\n"],
+  "mappings": "AAAA,YAAY,OAAO;AAMZ,MAAM,kBAAwC,EAAE;AAAA,EAAK,MAC1D,EAAE,MAAM;AAAA,IACN,EAAE,OAAO;AAAA,IACT,EAAE,OAAO;AAAA,IACT,EAAE,QAAQ;AAAA,IACV,EAAE,KAAK;AAAA,IACP,EAAE,MAAM,eAAe;AAAA,IACvB,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe;AAAA,EACtC,CAAC;AACH;AAEO,MAAM,mBAA0C,EAAE,OAAO,EAAE,OAAO,GAAG,eAAe;AAMpF,MAAM,mBAA0C;",
+  "names": []
+}

package/dist/modules/local-channel-socket.d.mts

@@ -0,0 +1,23 @@
+import type { ChannelRouteContextIface, WebSocketChannelRouteDefinitionIface } from "./channel.mjs";
+import { type ChannelSocketAction } from "./channel-socket.mjs";
+import type { JsonValue } from "./json.mjs";
+export interface ChannelSocketConnectionIface {
+    actions: AsyncIterable<ChannelSocketAction>;
+    send(data: string | Uint8Array): void;
+    close(): void;
+}
+export type ChannelSocketOpenResult = {
+    ok: true;
+    protocol: string | null;
+    metadata?: JsonValue;
+    connection: ChannelSocketConnectionIface;
+} | {
+    ok: false;
+    response: Response;
+};
+export declare const openChannelSocket: (args: {
+    handler: WebSocketChannelRouteDefinitionIface["handler"];
+    context: ChannelRouteContextIface;
+    signal: AbortSignal;
+    handshakeTimeoutMs?: number;
+}) => Promise<ChannelSocketOpenResult>;

package/dist/modules/local-channel-socket.mjs

@@ -0,0 +1,141 @@
+import {
+  ChannelSocketActionKind,
+  channelSocketData,
+  channelSocketMessage,
+  runChannelSocketHandler
+} from "./channel-socket.mjs";
+import { base64ToBytes } from "./sandbox/bytes.mjs";
+const byteLength = (text) => new TextEncoder().encode(text).byteLength;
+const openChannelSocket = async (args) => {
+  args.signal.throwIfAborted();
+  const closing = new AbortController();
+  const signal = AbortSignal.any([args.signal, closing.signal]);
+  let input = null;
+  let output = null;
+  const messages = new ReadableStream(
+    {
+      start: (controller) => {
+        input = controller;
+      }
+    },
+    {
+      highWaterMark: 8 * 1024 * 1024,
+      size: (data) => data instanceof Uint8Array ? data.byteLength : byteLength(data)
+    }
+  );
+  const actions = new ReadableStream(
+    {
+      start: (controller) => {
+        output = controller;
+      }
+    },
+    { highWaterMark: 8 * 1024 * 1024, size: (action) => byteLength(JSON.stringify(action)) }
+  );
+  const close = () => {
+    if (closing.signal.aborted) return;
+    closing.abort();
+    signal.removeEventListener("abort", close);
+    try {
+      input?.close();
+    } catch {
+    }
+    try {
+      output?.close();
+    } catch {
+    }
+  };
+  signal.addEventListener("abort", close, { once: true });
+  const readMessages = async function* () {
+    const reader2 = messages.getReader();
+    const cancel = () => {
+      void reader2.cancel().catch(() => void 0);
+    };
+    signal.addEventListener("abort", cancel, { once: true });
+    if (signal.aborted) cancel();
+    try {
+      for (; ; ) {
+        const item = await reader2.read();
+        if (item.done) return;
+        yield item.value;
+      }
+    } finally {
+      signal.removeEventListener("abort", cancel);
+      reader2.releaseLock();
+    }
+  };
+  const context = {
+    request: args.context.request,
+    secrets: {
+      get: (name) => {
+        signal.throwIfAborted();
+        return args.context.secrets.get(name);
+      }
+    },
+    receive: (value) => {
+      signal.throwIfAborted();
+      return args.context.receive(value);
+    }
+  };
+  const handshake = setTimeout(close, args.handshakeTimeoutMs ?? 3e4);
+  void runChannelSocketHandler({
+    handler: args.handler,
+    context,
+    signal,
+    messages: readMessages(),
+    emit: (action) => {
+      if (signal.aborted) return;
+      output?.enqueue(action);
+      if ((output?.desiredSize ?? 0) < 0) close();
+    }
+  }).catch(close).finally(close);
+  const reader = actions.getReader();
+  const first = await reader.read();
+  clearTimeout(handshake);
+  if (first.value?.kind === ChannelSocketActionKind.Reject) {
+    close();
+    reader.releaseLock();
+    const bytes = base64ToBytes(first.value.body);
+    return {
+      ok: false,
+      response: new Response(bytes.byteLength === 0 ? null : new Uint8Array(bytes), {
+        status: first.value.status,
+        headers: first.value.headers
+      })
+    };
+  }
+  if (first.value?.kind !== ChannelSocketActionKind.Accept) {
+    close();
+    reader.releaseLock();
+    return { ok: false, response: new Response("Channel socket did not accept", { status: 504 }) };
+  }
+  const outgoing = async function* () {
+    try {
+      for (; ; ) {
+        const item = await reader.read();
+        if (item.done) return;
+        yield item.value;
+      }
+    } finally {
+      reader.releaseLock();
+      close();
+    }
+  };
+  return {
+    ok: true,
+    protocol: first.value.protocol ?? null,
+    connection: {
+      actions: outgoing(),
+      close,
+      send: (data) => {
+        signal.throwIfAborted();
+        const message = channelSocketData(channelSocketMessage(data));
+        input?.enqueue(message);
+        if ((input?.desiredSize ?? 0) < 0) close();
+      }
+    }
+  };
+};
+export {
+  openChannelSocket
+};
+//# sourceMappingURL=local-channel-socket.mjs.map

package/dist/modules/local-channel-socket.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/local-channel-socket.ts"],
+  "sourcesContent": ["import type { ChannelRouteContextIface, WebSocketChannelRouteDefinitionIface } from \"./channel.mjs\";\nimport {\n  ChannelSocketActionKind,\n  channelSocketData,\n  channelSocketMessage,\n  runChannelSocketHandler,\n  type ChannelSocketAction,\n} from \"./channel-socket.mjs\";\nimport type { JsonValue } from \"./json.mjs\";\nimport { base64ToBytes } from \"./sandbox/bytes.mjs\";\nexport interface ChannelSocketConnectionIface {\n  actions: AsyncIterable<ChannelSocketAction>;\n  send(data: string | Uint8Array): void;\n  close(): void;\n}\n\nexport type ChannelSocketOpenResult =\n  | {\n      ok: true;\n      protocol: string | null;\n      metadata?: JsonValue;\n      connection: ChannelSocketConnectionIface;\n    }\n  | { ok: false; response: Response };\n\nconst byteLength = (text: string): number => new TextEncoder().encode(text).byteLength;\n\nexport const openChannelSocket = async (args: {\n  handler: WebSocketChannelRouteDefinitionIface['handler'];\n  context: ChannelRouteContextIface;\n  signal: AbortSignal;\n  handshakeTimeoutMs?: number;\n}): Promise<ChannelSocketOpenResult> => {\n  args.signal.throwIfAborted();\n  const closing = new AbortController();\n  const signal = AbortSignal.any([args.signal, closing.signal]);\n  let input: ReadableStreamDefaultController<string | Uint8Array> | null = null;\n  let output: ReadableStreamDefaultController<ChannelSocketAction> | null = null;\n  const messages = new ReadableStream<string | Uint8Array>(\n    {\n      start: (controller) => {\n        input = controller;\n      },\n    },\n    {\n      highWaterMark: 8 * 1024 * 1024,\n      size: (data) => (data instanceof Uint8Array ? data.byteLength : byteLength(data)),\n    },\n  );\n  const actions = new ReadableStream<ChannelSocketAction>(\n    {\n      start: (controller) => {\n        output = controller;\n      },\n    },\n    { highWaterMark: 8 * 1024 * 1024, size: (action) => byteLength(JSON.stringify(action)) },\n  );\n  const close = (): void => {\n    if (closing.signal.aborted) return;\n    closing.abort();\n    signal.removeEventListener('abort', close);\n    try {\n      input?.close();\n    } catch {\n      /* closed */\n    }\n    try {\n      output?.close();\n    } catch {\n      /* closed */\n    }\n  };\n  signal.addEventListener('abort', close, { once: true });\n  const readMessages = async function* (): AsyncGenerator<string | Uint8Array> {\n    const reader = messages.getReader();\n    const cancel = () => {\n      void reader.cancel().catch(() => undefined);\n    };\n    signal.addEventListener('abort', cancel, { once: true });\n    if (signal.aborted) cancel();\n    try {\n      for (;;) {\n        const item = await reader.read();\n        if (item.done) return;\n        yield item.value;\n      }\n    } finally {\n      signal.removeEventListener('abort', cancel);\n      reader.releaseLock();\n    }\n  };\n  const context: ChannelRouteContextIface = {\n    request: args.context.request,\n    secrets: {\n      get: (name) => {\n        signal.throwIfAborted();\n        return args.context.secrets.get(name);\n      },\n    },\n    receive: (value) => {\n      signal.throwIfAborted();\n      return args.context.receive(value);\n    },\n  };\n  const handshake = setTimeout(close, args.handshakeTimeoutMs ?? 30_000);\n  void runChannelSocketHandler({\n    handler: args.handler,\n    context,\n    signal,\n    messages: readMessages(),\n    emit: (action) => {\n      if (signal.aborted) return;\n      output?.enqueue(action);\n      if ((output?.desiredSize ?? 0) < 0) close();\n    },\n  })\n    .catch(close)\n    .finally(close);\n  const reader = actions.getReader();\n  const first = await reader.read();\n  clearTimeout(handshake);\n  if (first.value?.kind === ChannelSocketActionKind.Reject) {\n    close();\n    reader.releaseLock();\n    const bytes = base64ToBytes(first.value.body);\n    return {\n      ok: false,\n      response: new Response(bytes.byteLength === 0 ? null : new Uint8Array(bytes), {\n        status: first.value.status,\n        headers: first.value.headers,\n      }),\n    };\n  }\n  if (first.value?.kind !== ChannelSocketActionKind.Accept) {\n    close();\n    reader.releaseLock();\n    return { ok: false, response: new Response('Channel socket did not accept', { status: 504 }) };\n  }\n  const outgoing = async function* (): AsyncGenerator<ChannelSocketAction> {\n    try {\n      for (;;) {\n        const item = await reader.read();\n        if (item.done) return;\n        yield item.value;\n      }\n    } finally {\n      reader.releaseLock();\n      close();\n    }\n  };\n  return {\n    ok: true,\n    protocol: first.value.protocol ?? null,\n    connection: {\n      actions: outgoing(),\n      close,\n      send: (data) => {\n        signal.throwIfAborted();\n        const message = channelSocketData(channelSocketMessage(data));\n        input?.enqueue(message);\n        if ((input?.desiredSize ?? 0) < 0) close();\n      },\n    },\n  };\n};\n"],
+  "mappings": "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",
+  "names": ["reader"]
+}