@finalai/agents 0.8.0

package/dist/modules/agent-client/test-fakes.mjs

@@ -0,0 +1,94 @@
+import * as z from "zod";
+const headerRecordSchema = z.record(z.string(), z.string());
+const createFakeFetch = (routes) => {
+  const requests = [];
+  const fetch = async (input, init) => {
+    const url = new URL(input);
+    const bodyText = z.string().safeParse(init.body);
+    const request = {
+      method: init.method ?? "GET",
+      path: url.pathname,
+      query: url.searchParams,
+      headers: headerRecordSchema.safeParse(init.headers).data ?? {},
+      credentials: init.credentials,
+      body: bodyText.success ? z.json().parse(JSON.parse(bodyText.data)) : null
+    };
+    requests.push(request);
+    const route = routes[`${request.method} ${request.path}`];
+    if (route == null) {
+      return new Response(JSON.stringify({ error: { code: "not_found", message: "no route" } }), {
+        status: 404
+      });
+    }
+    const response = route(request);
+    const status = response.status ?? 200;
+    const body = status === 204 ? null : response.text ?? JSON.stringify(response.json ?? {});
+    return new Response(body, { status });
+  };
+  return { fetch, requests };
+};
+const createFakeTransport = () => {
+  const listeners = /* @__PURE__ */ new Map();
+  const subscriptions = [];
+  const transport = {
+    subscribe: (topic, onFrame) => {
+      subscriptions.push(topic);
+      const set = listeners.get(topic) ?? /* @__PURE__ */ new Set();
+      set.add(onFrame);
+      listeners.set(topic, set);
+      return () => set.delete(onFrame);
+    }
+  };
+  const emit = (topic, frame) => {
+    for (const listener of [...listeners.get(topic) ?? []]) listener(frame);
+  };
+  const listenerCount = (topic) => listeners.get(topic)?.size ?? 0;
+  return { transport, emit, subscriptions, listenerCount };
+};
+let cursor = 0;
+const eventFrame = (args) => {
+  cursor += 1;
+  return {
+    type: "event",
+    topic: args.topic,
+    cursor: `${cursor}-0`,
+    eventKey: `${args.kind}:${cursor}`,
+    kind: args.kind,
+    payload: args.payload,
+    createdAt: "2026-10-09T14:02:12.004Z"
+  };
+};
+const sessionUpdateFrame = (args) => ({
+  seq: args.seq,
+  direction: args.direction ?? "agent_to_client",
+  at: "2026-10-09T14:02:12.004Z",
+  frame: {
+    jsonrpc: "2.0",
+    method: "session/update",
+    params: { sessionId: "ases_1", update: args.update }
+  }
+});
+const promptFrame = (seq) => ({
+  seq,
+  direction: "client_to_agent",
+  at: "2026-10-09T14:02:11.000Z",
+  frame: {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "session/prompt",
+    params: { sessionId: "ases_1", prompt: [] }
+  }
+});
+const flush = async () => {
+  for (let index = 0; index < 10; index += 1)
+    await new Promise((resolve) => setTimeout(resolve, 0));
+};
+export {
+  createFakeFetch,
+  createFakeTransport,
+  eventFrame,
+  flush,
+  promptFrame,
+  sessionUpdateFrame
+};
+//# sourceMappingURL=test-fakes.mjs.map

package/dist/modules/agent-client/test-fakes.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/test-fakes.ts"],
+  "sourcesContent": ["import type { JsonValue } from '@finalai/agent-protocol';\nimport * as z from 'zod';\nimport type { FetchIface } from \"./http.mjs\";\nimport type { RealtimeTransportFrameIface, RealtimeTransportIface } from \"./realtime.mjs\";\n\n// Dependency seams for SDK tests: a routed fake fetch and an in-memory\n// realtime transport. No module mocking.\n\nexport interface RecordedRequestIface {\n  method: string;\n  path: string;\n  query: URLSearchParams;\n  headers: Record<string, string>;\n  credentials: RequestCredentials | undefined;\n  body: JsonValue | null;\n}\n\nexport interface FakeResponseIface {\n  status?: number;\n  json?: JsonValue;\n  text?: string;\n}\n\nexport type FakeRoute = (request: RecordedRequestIface) => FakeResponseIface;\n\nconst headerRecordSchema = z.record(z.string(), z.string());\n\nexport const createFakeFetch = (routes: Record<string, FakeRoute>) => {\n  const requests: RecordedRequestIface[] = [];\n  const fetch: FetchIface = async (input, init) => {\n    const url = new URL(input);\n    const bodyText = z.string().safeParse(init.body);\n    const request: RecordedRequestIface = {\n      method: init.method ?? 'GET',\n      path: url.pathname,\n      query: url.searchParams,\n      headers: headerRecordSchema.safeParse(init.headers).data ?? {},\n      credentials: init.credentials,\n      body: bodyText.success ? z.json().parse(JSON.parse(bodyText.data)) : null,\n    };\n    requests.push(request);\n    const route = routes[`${request.method} ${request.path}`];\n    if (route == null) {\n      return new Response(JSON.stringify({ error: { code: 'not_found', message: 'no route' } }), {\n        status: 404,\n      });\n    }\n    const response = route(request);\n    const status = response.status ?? 200;\n    const body = status === 204 ? null : (response.text ?? JSON.stringify(response.json ?? {}));\n    return new Response(body, { status });\n  };\n  return { fetch, requests };\n};\n\nexport const createFakeTransport = () => {\n  const listeners = new Map<string, Set<(frame: RealtimeTransportFrameIface) => void>>();\n  const subscriptions: string[] = [];\n  const transport: RealtimeTransportIface = {\n    subscribe: (topic, onFrame) => {\n      subscriptions.push(topic);\n      const set = listeners.get(topic) ?? new Set();\n      set.add(onFrame);\n      listeners.set(topic, set);\n      return () => set.delete(onFrame);\n    },\n  };\n  const emit = (topic: string, frame: RealtimeTransportFrameIface): void => {\n    for (const listener of [...(listeners.get(topic) ?? [])]) listener(frame);\n  };\n  const listenerCount = (topic: string): number => listeners.get(topic)?.size ?? 0;\n  return { transport, emit, subscriptions, listenerCount };\n};\n\nlet cursor = 0;\n\nexport const eventFrame = (args: {\n  topic: string;\n  kind: string;\n  payload: JsonValue;\n}): RealtimeTransportFrameIface => {\n  cursor += 1;\n  return {\n    type: 'event',\n    topic: args.topic,\n    cursor: `${cursor}-0`,\n    eventKey: `${args.kind}:${cursor}`,\n    kind: args.kind,\n    payload: args.payload,\n    createdAt: '2026-10-09T14:02:12.004Z',\n  };\n};\n\nexport const sessionUpdateFrame = (args: {\n  seq: number;\n  update: JsonValue;\n  direction?: string;\n}): JsonValue => ({\n  seq: args.seq,\n  direction: args.direction ?? 'agent_to_client',\n  at: '2026-10-09T14:02:12.004Z',\n  frame: {\n    jsonrpc: '2.0',\n    method: 'session/update',\n    params: { sessionId: 'ases_1', update: args.update },\n  },\n});\n\nexport const promptFrame = (seq: number): JsonValue => ({\n  seq,\n  direction: 'client_to_agent',\n  at: '2026-10-09T14:02:11.000Z',\n  frame: {\n    jsonrpc: '2.0',\n    id: 1,\n    method: 'session/prompt',\n    params: { sessionId: 'ases_1', prompt: [] },\n  },\n});\n\n/** Lets pending promise callbacks (replay fetches) run. */\nexport const flush = async (): Promise<void> => {\n  for (let index = 0; index < 10; index += 1)\n    await new Promise((resolve) => setTimeout(resolve, 0));\n};\n"],
+  "mappings": "AACA,YAAY,OAAO;AAwBnB,MAAM,qBAAqB,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC;AAEnD,MAAM,kBAAkB,CAAC,WAAsC;AACpE,QAAM,WAAmC,CAAC;AAC1C,QAAM,QAAoB,OAAO,OAAO,SAAS;AAC/C,UAAM,MAAM,IAAI,IAAI,KAAK;AACzB,UAAM,WAAW,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI;AAC/C,UAAM,UAAgC;AAAA,MACpC,QAAQ,KAAK,UAAU;AAAA,MACvB,MAAM,IAAI;AAAA,MACV,OAAO,IAAI;AAAA,MACX,SAAS,mBAAmB,UAAU,KAAK,OAAO,EAAE,QAAQ,CAAC;AAAA,MAC7D,aAAa,KAAK;AAAA,MAClB,MAAM,SAAS,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,SAAS,IAAI,CAAC,IAAI;AAAA,IACvE;AACA,aAAS,KAAK,OAAO;AACrB,UAAM,QAAQ,OAAO,GAAG,QAAQ,MAAM,IAAI,QAAQ,IAAI,EAAE;AACxD,QAAI,SAAS,MAAM;AACjB,aAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,SAAS,WAAW,EAAE,CAAC,GAAG;AAAA,QACzF,QAAQ;AAAA,MACV,CAAC;AAAA,IACH;AACA,UAAM,WAAW,MAAM,OAAO;AAC9B,UAAM,SAAS,SAAS,UAAU;AAClC,UAAM,OAAO,WAAW,MAAM,OAAQ,SAAS,QAAQ,KAAK,UAAU,SAAS,QAAQ,CAAC,CAAC;AACzF,WAAO,IAAI,SAAS,MAAM,EAAE,OAAO,CAAC;AAAA,EACtC;AACA,SAAO,EAAE,OAAO,SAAS;AAC3B;AAEO,MAAM,sBAAsB,MAAM;AACvC,QAAM,YAAY,oBAAI,IAA+D;AACrF,QAAM,gBAA0B,CAAC;AACjC,QAAM,YAAoC;AAAA,IACxC,WAAW,CAAC,OAAO,YAAY;AAC7B,oBAAc,KAAK,KAAK;AACxB,YAAM,MAAM,UAAU,IAAI,KAAK,KAAK,oBAAI,IAAI;AAC5C,UAAI,IAAI,OAAO;AACf,gBAAU,IAAI,OAAO,GAAG;AACxB,aAAO,MAAM,IAAI,OAAO,OAAO;AAAA,IACjC;AAAA,EACF;AACA,QAAM,OAAO,CAAC,OAAe,UAA6C;AACxE,eAAW,YAAY,CAAC,GAAI,UAAU,IAAI,KAAK,KAAK,CAAC,CAAE,EAAG,UAAS,KAAK;AAAA,EAC1E;AACA,QAAM,gBAAgB,CAAC,UAA0B,UAAU,IAAI,KAAK,GAAG,QAAQ;AAC/E,SAAO,EAAE,WAAW,MAAM,eAAe,cAAc;AACzD;AAEA,IAAI,SAAS;AAEN,MAAM,aAAa,CAAC,SAIQ;AACjC,YAAU;AACV,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO,KAAK;AAAA,IACZ,QAAQ,GAAG,MAAM;AAAA,IACjB,UAAU,GAAG,KAAK,IAAI,IAAI,MAAM;AAAA,IAChC,MAAM,KAAK;AAAA,IACX,SAAS,KAAK;AAAA,IACd,WAAW;AAAA,EACb;AACF;AAEO,MAAM,qBAAqB,CAAC,UAIjB;AAAA,EAChB,KAAK,KAAK;AAAA,EACV,WAAW,KAAK,aAAa;AAAA,EAC7B,IAAI;AAAA,EACJ,OAAO;AAAA,IACL,SAAS;AAAA,IACT,QAAQ;AAAA,IACR,QAAQ,EAAE,WAAW,UAAU,QAAQ,KAAK,OAAO;AAAA,EACrD;AACF;AAEO,MAAM,cAAc,CAAC,SAA4B;AAAA,EACtD;AAAA,EACA,WAAW;AAAA,EACX,IAAI;AAAA,EACJ,OAAO;AAAA,IACL,SAAS;AAAA,IACT,IAAI;AAAA,IACJ,QAAQ;AAAA,IACR,QAAQ,EAAE,WAAW,UAAU,QAAQ,CAAC,EAAE;AAAA,EAC5C;AACF;AAGO,MAAM,QAAQ,YAA2B;AAC9C,WAAS,QAAQ,GAAG,QAAQ,IAAI,SAAS;AACvC,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,CAAC,CAAC;AACzD;",
+  "names": []
+}

package/dist/modules/authoring/approval.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/approval';

package/dist/modules/authoring/approval.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/approval";
+//# sourceMappingURL=approval.mjs.map

package/dist/modules/authoring/approval.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/approval.ts"],
+  "sourcesContent": ["export * from '@finalai/agent-definition/approval';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/channels.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/channels';

package/dist/modules/authoring/channels.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/channels";
+//# sourceMappingURL=channels.mjs.map

package/dist/modules/authoring/channels.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/channels.ts"],
+  "sourcesContent": ["export * from '@finalai/agent-definition/channels';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/final-channel.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/final-agent-provider/channels/final';

package/dist/modules/authoring/final-channel.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/final-agent-provider/channels/final";
+//# sourceMappingURL=final-channel.mjs.map

package/dist/modules/authoring/final-channel.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/final-channel.ts"],
+  "sourcesContent": ["export * from '@finalai/final-agent-provider/channels/final';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/hooks.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/hooks';

package/dist/modules/authoring/hooks.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/hooks";
+//# sourceMappingURL=hooks.mjs.map

package/dist/modules/authoring/hooks.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/hooks.ts"],
+  "sourcesContent": ["export * from '@finalai/agent-definition/hooks';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/index.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/authoring';

package/dist/modules/authoring/index.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/authoring";
+//# sourceMappingURL=index.mjs.map

package/dist/modules/authoring/index.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/index.ts"],
+  "sourcesContent": ["// Agent authoring helpers from @finalai/agent-definition.\nexport * from '@finalai/agent-definition/authoring';\n"],
+  "mappings": "AACA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/instructions.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/instructions';

package/dist/modules/authoring/instructions.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/instructions";
+//# sourceMappingURL=instructions.mjs.map

package/dist/modules/authoring/instructions.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/instructions.ts"],
+  "sourcesContent": ["export * from '@finalai/agent-definition/instructions';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/authoring/providers.d.mts

@@ -0,0 +1,2 @@
+export type { ClaudeModelId, CodexCliModelId, CodexResponsesLiteModelId, FinalHarnessModelId, HarnessBindingOutputIface, LocalStdioConfigInputIface, PiModelId, RemoteAcpConfigInputIface, RemoteClaudeCodeConfigInputIface, RemoteClientTlsInputIface, RemoteCodexConfigInputIface, RemotePiConfigInputIface, SecretRefIface, ServerlessFinalConfigInputIface, ServerlessNanocodeClaudeConfigInputIface, ServerlessNanocodeCodexConfigInputIface, ServerlessPiConfigInputIface, } from '@finalai/final-agent-provider/harnesses';
+export type { ComputerInlineGuideInputIface, ComputerInputIface, ComputerParametersInputIface, ComputerRepositoryInputIface, ComputerSetupGuideInputIface, DeviceInputIface, InstalledSandboxEnvironmentIface, InstalledSandboxOpenRequestIface, SandboxOpenInputIface, } from '@finalai/final-agent-provider/sandboxes';

package/dist/modules/authoring/providers.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=providers.mjs.map

package/dist/modules/authoring/providers.mjs.map

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

package/dist/modules/authoring/tools.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-definition/tools';

package/dist/modules/authoring/tools.mjs

@@ -0,0 +1,2 @@
+export * from "@finalai/agent-definition/tools";
+//# sourceMappingURL=tools.mjs.map

package/dist/modules/authoring/tools.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/authoring/tools.ts"],
+  "sourcesContent": ["export * from '@finalai/agent-definition/tools';\n"],
+  "mappings": "AAAA,cAAc;",
+  "names": []
+}

package/dist/modules/cli/build.d.mts

@@ -0,0 +1,22 @@
+import { type CompileResultIface } from '@finalai/agent-definition/compiler';
+import type { AgentClientIface } from "../agent-client/client.mjs";
+import { type OutputIface } from "./output.mjs";
+export declare const COMPILE_OUTPUT_DIR: string;
+export interface CompileDirectoryArgsIface {
+    source: {
+        dir: string;
+    } | {
+        files: Record<string, string>;
+    };
+    client: AgentClientIface | null;
+    output: OutputIface;
+}
+export declare const compileAndPrint: (args: CompileDirectoryArgsIface) => Promise<{
+    result: CompileResultIface;
+    ok: boolean;
+}>;
+export declare const runBuild: (args: {
+    dir: string;
+    client: AgentClientIface | null;
+    output: OutputIface;
+}) => Promise<number>;

package/dist/modules/cli/build.mjs

@@ -0,0 +1,77 @@
+import {
+  DiagnosticSeverity,
+  hasErrors
+} from "@finalai/agent-definition/compiler";
+import { ProviderRefKind } from "@finalai/agent-provider";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { compile } from "../compile.mjs";
+import { createHarnessDescriptions } from "./harness-descriptions.mjs";
+import {
+  diagnosticLine,
+  hookLines,
+  manifestSummaryLines,
+  reportLines
+} from "./output.mjs";
+const COMPILE_OUTPUT_DIR = join(".final", "compile");
+const compileAndPrint = async (args) => {
+  const options = {
+    ...args.source,
+    // Installed harnesses are described by the platform (needs a client); a
+    // bundle harness by its own describe, run locally.
+    harnessDescriptions: createHarnessDescriptions({ client: args.client, output: args.output })
+  };
+  const result = await compile(options);
+  const { stdout, stderr } = args.output;
+  if (result.manifest != null) {
+    for (const line of manifestSummaryLines(result.manifest)) stdout(line);
+    for (const line of hookLines(result.manifest)) stdout(line);
+  }
+  if (result.report != null) for (const line of reportLines(result.report)) stdout(line);
+  else if (args.client == null && result.manifest != null && result.manifest.harness.harness.kind !== ProviderRefKind.Bundle)
+    stdout("compatibility: not checked (set FINAL_API_KEY to check the installed harness)");
+  for (const item of result.diagnostics) {
+    (item.severity === DiagnosticSeverity.Error ? stderr : stdout)(diagnosticLine(item));
+  }
+  const ok = !hasErrors(result.diagnostics) && result.manifest != null && result.report?.ok !== false;
+  return { result, ok };
+};
+const prettyJson = (value) => `${JSON.stringify(value, null, 2)}
+`;
+const writeOutputs = async (dir, result) => {
+  const out = join(dir, COMPILE_OUTPUT_DIR);
+  await rm(out, { recursive: true, force: true });
+  await mkdir(out, { recursive: true });
+  await writeFile(join(out, "diagnostics.json"), prettyJson(result.diagnostics));
+  if (result.manifest != null)
+    await writeFile(join(out, "manifest.json"), prettyJson(result.manifest));
+  if (result.report != null) await writeFile(join(out, "report.json"), prettyJson(result.report));
+  if (result.bundle != null) {
+    await writeFile(join(out, "bundle.mjs"), result.bundle.code);
+    await writeFile(
+      join(out, "modules.json"),
+      prettyJson({
+        hash: result.bundle.hash,
+        modules: result.bundle.modules,
+        sandboxOpeners: result.bundle.sandboxOpeners
+      })
+    );
+  }
+  return out;
+};
+const runBuild = async (args) => {
+  const { result, ok } = await compileAndPrint({
+    source: { dir: args.dir },
+    client: args.client,
+    output: args.output
+  });
+  const out = await writeOutputs(args.dir, result);
+  args.output.stdout(`wrote ${out}`);
+  return ok ? 0 : 1;
+};
+export {
+  COMPILE_OUTPUT_DIR,
+  compileAndPrint,
+  runBuild
+};
+//# sourceMappingURL=build.mjs.map

package/dist/modules/cli/build.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/build.ts"],
+  "sourcesContent": ["import {\n  DiagnosticSeverity,\n  hasErrors,\n  type CompileOptionsIface,\n  type CompileResultIface,\n} from '@finalai/agent-definition/compiler';\nimport { ProviderRefKind } from '@finalai/agent-provider';\nimport { mkdir, rm, writeFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport type { AgentClientIface } from \"../agent-client/client.mjs\";\nimport { compile } from \"../compile.mjs\";\nimport { createHarnessDescriptions } from \"./harness-descriptions.mjs\";\nimport {\n  diagnosticLine,\n  hookLines,\n  manifestSummaryLines,\n  reportLines,\n  type OutputIface,\n} from \"./output.mjs\";\n\n// `final agents build`: compiles the agent directory, prints the\n// manifest summary, the compatibility report for the chosen harness, the\n// diagnostics and the hooks, and writes the outputs under `.final/compile/`.\n\nexport const COMPILE_OUTPUT_DIR = join('.final', 'compile');\n\nexport interface CompileDirectoryArgsIface {\n  // The directory on disk, or the files that will be committed.\n  source: { dir: string } | { files: Record<string, string> };\n  // Null compiles without a compatibility report (no API key).\n  client: AgentClientIface | null;\n  output: OutputIface;\n}\n\nexport const compileAndPrint = async (\n  args: CompileDirectoryArgsIface,\n): Promise<{ result: CompileResultIface; ok: boolean }> => {\n  const options: CompileOptionsIface = {\n    ...args.source,\n    // Installed harnesses are described by the platform (needs a client); a\n    // bundle harness by its own describe, run locally.\n    harnessDescriptions: createHarnessDescriptions({ client: args.client, output: args.output }),\n  };\n  const result = await compile(options);\n  const { stdout, stderr } = args.output;\n  if (result.manifest != null) {\n    for (const line of manifestSummaryLines(result.manifest)) stdout(line);\n    for (const line of hookLines(result.manifest)) stdout(line);\n  }\n  if (result.report != null) for (const line of reportLines(result.report)) stdout(line);\n  else if (\n    args.client == null &&\n    result.manifest != null &&\n    result.manifest.harness.harness.kind !== ProviderRefKind.Bundle\n  )\n    stdout('compatibility: not checked (set FINAL_API_KEY to check the installed harness)');\n  for (const item of result.diagnostics) {\n    (item.severity === DiagnosticSeverity.Error ? stderr : stdout)(diagnosticLine(item));\n  }\n  const ok =\n    !hasErrors(result.diagnostics) && result.manifest != null && result.report?.ok !== false;\n  return { result, ok };\n};\n\nconst prettyJson = (value: CompileOutputJson): string => `${JSON.stringify(value, null, 2)}\\n`;\n\ntype CompileOutputJson =\n  | CompileResultIface['diagnostics']\n  | NonNullable<CompileResultIface['manifest']>\n  | NonNullable<CompileResultIface['report']>\n  | { hash: string; modules: Record<string, string>; sandboxOpeners: Record<string, string> };\n\nconst writeOutputs = async (dir: string, result: CompileResultIface): Promise<string> => {\n  const out = join(dir, COMPILE_OUTPUT_DIR);\n  await rm(out, { recursive: true, force: true });\n  await mkdir(out, { recursive: true });\n  await writeFile(join(out, 'diagnostics.json'), prettyJson(result.diagnostics));\n  if (result.manifest != null)\n    await writeFile(join(out, 'manifest.json'), prettyJson(result.manifest));\n  if (result.report != null) await writeFile(join(out, 'report.json'), prettyJson(result.report));\n  if (result.bundle != null) {\n    await writeFile(join(out, 'bundle.mjs'), result.bundle.code);\n    await writeFile(\n      join(out, 'modules.json'),\n      prettyJson({\n        hash: result.bundle.hash,\n        modules: result.bundle.modules,\n        sandboxOpeners: result.bundle.sandboxOpeners,\n      }),\n    );\n  }\n  return out;\n};\n\nexport const runBuild = async (args: {\n  dir: string;\n  client: AgentClientIface | null;\n  output: OutputIface;\n}): Promise<number> => {\n  const { result, ok } = await compileAndPrint({\n    source: { dir: args.dir },\n    client: args.client,\n    output: args.output,\n  });\n  const out = await writeOutputs(args.dir, result);\n  args.output.stdout(`wrote ${out}`);\n  return ok ? 0 : 1;\n};\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AACP,SAAS,uBAAuB;AAChC,SAAS,OAAO,IAAI,iBAAiB;AACrC,SAAS,YAAY;AAErB,SAAS,eAAe;AACxB,SAAS,iCAAiC;AAC1C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAMA,MAAM,qBAAqB,KAAK,UAAU,SAAS;AAUnD,MAAM,kBAAkB,OAC7B,SACyD;AACzD,QAAM,UAA+B;AAAA,IACnC,GAAG,KAAK;AAAA;AAAA;AAAA,IAGR,qBAAqB,0BAA0B,EAAE,QAAQ,KAAK,QAAQ,QAAQ,KAAK,OAAO,CAAC;AAAA,EAC7F;AACA,QAAM,SAAS,MAAM,QAAQ,OAAO;AACpC,QAAM,EAAE,QAAQ,OAAO,IAAI,KAAK;AAChC,MAAI,OAAO,YAAY,MAAM;AAC3B,eAAW,QAAQ,qBAAqB,OAAO,QAAQ,EAAG,QAAO,IAAI;AACrE,eAAW,QAAQ,UAAU,OAAO,QAAQ,EAAG,QAAO,IAAI;AAAA,EAC5D;AACA,MAAI,OAAO,UAAU,KAAM,YAAW,QAAQ,YAAY,OAAO,MAAM,EAAG,QAAO,IAAI;AAAA,WAEnF,KAAK,UAAU,QACf,OAAO,YAAY,QACnB,OAAO,SAAS,QAAQ,QAAQ,SAAS,gBAAgB;AAEzD,WAAO,+EAA+E;AACxF,aAAW,QAAQ,OAAO,aAAa;AACrC,KAAC,KAAK,aAAa,mBAAmB,QAAQ,SAAS,QAAQ,eAAe,IAAI,CAAC;AAAA,EACrF;AACA,QAAM,KACJ,CAAC,UAAU,OAAO,WAAW,KAAK,OAAO,YAAY,QAAQ,OAAO,QAAQ,OAAO;AACrF,SAAO,EAAE,QAAQ,GAAG;AACtB;AAEA,MAAM,aAAa,CAAC,UAAqC,GAAG,KAAK,UAAU,OAAO,MAAM,CAAC,CAAC;AAAA;AAQ1F,MAAM,eAAe,OAAO,KAAa,WAAgD;AACvF,QAAM,MAAM,KAAK,KAAK,kBAAkB;AACxC,QAAM,GAAG,KAAK,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AAC9C,QAAM,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;AACpC,QAAM,UAAU,KAAK,KAAK,kBAAkB,GAAG,WAAW,OAAO,WAAW,CAAC;AAC7E,MAAI,OAAO,YAAY;AACrB,UAAM,UAAU,KAAK,KAAK,eAAe,GAAG,WAAW,OAAO,QAAQ,CAAC;AACzE,MAAI,OAAO,UAAU,KAAM,OAAM,UAAU,KAAK,KAAK,aAAa,GAAG,WAAW,OAAO,MAAM,CAAC;AAC9F,MAAI,OAAO,UAAU,MAAM;AACzB,UAAM,UAAU,KAAK,KAAK,YAAY,GAAG,OAAO,OAAO,IAAI;AAC3D,UAAM;AAAA,MACJ,KAAK,KAAK,cAAc;AAAA,MACxB,WAAW;AAAA,QACT,MAAM,OAAO,OAAO;AAAA,QACpB,SAAS,OAAO,OAAO;AAAA,QACvB,gBAAgB,OAAO,OAAO;AAAA,MAChC,CAAC;AAAA,IACH;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,WAAW,OAAO,SAIR;AACrB,QAAM,EAAE,QAAQ,GAAG,IAAI,MAAM,gBAAgB;AAAA,IAC3C,QAAQ,EAAE,KAAK,KAAK,IAAI;AAAA,IACxB,QAAQ,KAAK;AAAA,IACb,QAAQ,KAAK;AAAA,EACf,CAAC;AACD,QAAM,MAAM,MAAM,aAAa,KAAK,KAAK,MAAM;AAC/C,OAAK,OAAO,OAAO,SAAS,GAAG,EAAE;AACjC,SAAO,KAAK,IAAI;AAClB;",
+  "names": []
+}

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

@@ -0,0 +1,9 @@
+import type { IncomingMessage, Server } from 'node:http';
+export declare const attachDevChannelSockets: (args: {
+    server: Server;
+    open: (incoming: IncomingMessage, signal: AbortSignal) => Promise<ChannelSocketOpenResult>;
+    log: (message: string) => void;
+}) => {
+    close: () => Promise<void>;
+};
+import type { ChannelSocketOpenResult } from '@finalai/agent-provider/local-channel-socket';

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

@@ -0,0 +1,114 @@
+import {
+  CHANNEL_SOCKET_MAX_MESSAGE_BYTES,
+  ChannelSocketActionKind,
+  channelSocketData
+} from "@finalai/agent-provider/channel-socket";
+import { WebSocketServer } from "ws";
+const attachDevChannelSockets = (args) => {
+  const protocols = /* @__PURE__ */ new WeakMap();
+  const sockets = new WebSocketServer({
+    noServer: true,
+    perMessageDeflate: false,
+    maxPayload: CHANNEL_SOCKET_MAX_MESSAGE_BYTES,
+    handleProtocols: (_offered, request) => protocols.get(request) ?? false
+  });
+  const controllers = /* @__PURE__ */ new Set();
+  let stopped = false;
+  const reject = async (socket, response) => {
+    const body = Buffer.from(await response.arrayBuffer());
+    const headers = new Headers(response.headers);
+    headers.set("connection", "close");
+    headers.set("content-length", String(body.byteLength));
+    socket.write(
+      `HTTP/1.1 ${response.status} ${response.statusText}\r
+${[...headers].map(([name, value]) => `${name}: ${value}`).join("\r\n")}\r
+\r
+`
+    );
+    socket.end(body);
+  };
+  args.server.on("upgrade", (incoming, socket, head) => {
+    const controller = new AbortController();
+    controllers.add(controller);
+    socket.once("close", () => controller.abort());
+    socket.once("error", () => controller.abort());
+    let upgraded = false;
+    void (async () => {
+      if (stopped) {
+        await reject(socket, new Response("Dev server stopping", { status: 503 }));
+        return;
+      }
+      const opened = await args.open(incoming, controller.signal);
+      if (!opened.ok) {
+        await reject(socket, opened.response);
+        return;
+      }
+      if (controller.signal.aborted) {
+        opened.connection.close();
+        return;
+      }
+      protocols.set(incoming, opened.protocol);
+      sockets.handleUpgrade(incoming, socket, head, (peer) => {
+        upgraded = true;
+        const cleanup = () => {
+          opened.connection.close();
+          controller.abort();
+          controllers.delete(controller);
+        };
+        peer.once("close", cleanup);
+        peer.once("error", cleanup);
+        peer.on("message", (raw, binary) => {
+          try {
+            const bytes = Array.isArray(raw) ? Buffer.concat(raw) : Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+            opened.connection.send(binary ? bytes : bytes.toString("utf8"));
+          } catch {
+            peer.close(1013, "Channel input unavailable");
+            cleanup();
+          }
+        });
+        void (async () => {
+          for await (const action of opened.connection.actions) {
+            if (peer.readyState !== peer.OPEN) break;
+            if (action.kind === ChannelSocketActionKind.Message) {
+              if (peer.bufferedAmount > 8 * 1024 * 1024) {
+                peer.close(1013, "Channel output fell behind");
+                break;
+              }
+              peer.send(channelSocketData(action));
+            } else if (action.kind === ChannelSocketActionKind.Close) {
+              peer.close(action.code ?? 1e3, action.reason ?? "");
+              break;
+            }
+          }
+          if (peer.readyState === peer.OPEN) peer.close(1e3);
+        })().catch((cause) => {
+          args.log(
+            `socket route failed: ${cause instanceof Error ? cause.message : String(cause)}`
+          );
+          if (peer.readyState === peer.OPEN) peer.close(1011, "Channel route failed");
+        }).finally(cleanup);
+      });
+    })().catch(async (cause) => {
+      args.log(`socket route failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+      if (!socket.destroyed)
+        await reject(socket, new Response("Channel route failed", { status: 500 }));
+    }).finally(() => {
+      if (!upgraded) {
+        controller.abort();
+        controllers.delete(controller);
+      }
+    }).catch(() => socket.destroy());
+  });
+  return {
+    close: async () => {
+      stopped = true;
+      for (const controller of controllers) controller.abort();
+      for (const peer of sockets.clients) peer.terminate();
+      await new Promise((resolve) => sockets.close(() => resolve()));
+    }
+  };
+};
+export {
+  attachDevChannelSockets
+};
+//# sourceMappingURL=channel-socket.mjs.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/cli/channel-socket.ts"],
+  "sourcesContent": ["import {\n  CHANNEL_SOCKET_MAX_MESSAGE_BYTES,\n  ChannelSocketActionKind,\n  channelSocketData,\n} from '@finalai/agent-provider/channel-socket';\nimport type { IncomingMessage, Server } from 'node:http';\nimport type { Duplex } from 'node:stream';\nimport { WebSocketServer } from 'ws';\n\n// Keeps an accepted local route on its original compiled bundle until disconnect.\nexport const attachDevChannelSockets = (args: {\n  server: Server;\n  open: (incoming: IncomingMessage, signal: AbortSignal) => Promise<ChannelSocketOpenResult>;\n  log: (message: string) => void;\n}) => {\n  const protocols = new WeakMap<IncomingMessage, string | null>();\n  const sockets = new WebSocketServer({\n    noServer: true,\n    perMessageDeflate: false,\n    maxPayload: CHANNEL_SOCKET_MAX_MESSAGE_BYTES,\n    handleProtocols: (_offered, request) => protocols.get(request) ?? false,\n  });\n  const controllers = new Set<AbortController>();\n  let stopped = false;\n  const reject = async (socket: Duplex, response: Response): Promise<void> => {\n    const body = Buffer.from(await response.arrayBuffer());\n    const headers = new Headers(response.headers);\n    headers.set('connection', 'close');\n    headers.set('content-length', String(body.byteLength));\n    socket.write(\n      `HTTP/1.1 ${response.status} ${response.statusText}\\r\\n${[...headers].map(([name, value]) => `${name}: ${value}`).join('\\r\\n')}\\r\\n\\r\\n`,\n    );\n    socket.end(body);\n  };\n  args.server.on('upgrade', (incoming, socket, head) => {\n    const controller = new AbortController();\n    controllers.add(controller);\n    socket.once('close', () => controller.abort());\n    socket.once('error', () => controller.abort());\n    let upgraded = false;\n    void (async () => {\n      if (stopped) {\n        await reject(socket, new Response('Dev server stopping', { status: 503 }));\n        return;\n      }\n      const opened = await args.open(incoming, controller.signal);\n      if (!opened.ok) {\n        await reject(socket, opened.response);\n        return;\n      }\n      if (controller.signal.aborted) {\n        opened.connection.close();\n        return;\n      }\n      protocols.set(incoming, opened.protocol);\n      sockets.handleUpgrade(incoming, socket, head, (peer) => {\n        upgraded = true;\n        const cleanup = (): void => {\n          opened.connection.close();\n          controller.abort();\n          controllers.delete(controller);\n        };\n        peer.once('close', cleanup);\n        peer.once('error', cleanup);\n        peer.on('message', (raw, binary) => {\n          try {\n            const bytes = Array.isArray(raw)\n              ? Buffer.concat(raw)\n              : Buffer.isBuffer(raw)\n                ? raw\n                : Buffer.from(raw);\n            opened.connection.send(binary ? bytes : bytes.toString('utf8'));\n          } catch {\n            peer.close(1013, 'Channel input unavailable');\n            cleanup();\n          }\n        });\n        void (async () => {\n          for await (const action of opened.connection.actions) {\n            if (peer.readyState !== peer.OPEN) break;\n            if (action.kind === ChannelSocketActionKind.Message) {\n              if (peer.bufferedAmount > 8 * 1024 * 1024) {\n                peer.close(1013, 'Channel output fell behind');\n                break;\n              }\n              peer.send(channelSocketData(action));\n            } else if (action.kind === ChannelSocketActionKind.Close) {\n              peer.close(action.code ?? 1000, action.reason ?? '');\n              break;\n            }\n          }\n          if (peer.readyState === peer.OPEN) peer.close(1000);\n        })()\n          .catch((cause: unknown) => {\n            args.log(\n              `socket route failed: ${cause instanceof Error ? cause.message : String(cause)}`,\n            );\n            if (peer.readyState === peer.OPEN) peer.close(1011, 'Channel route failed');\n          })\n          .finally(cleanup);\n      });\n    })()\n      .catch(async (cause: unknown) => {\n        args.log(`socket route failed: ${cause instanceof Error ? cause.message : String(cause)}`);\n        if (!socket.destroyed)\n          await reject(socket, new Response('Channel route failed', { status: 500 }));\n      })\n      .finally(() => {\n        if (!upgraded) {\n          controller.abort();\n          controllers.delete(controller);\n        }\n      })\n      .catch(() => socket.destroy());\n  });\n  return {\n    close: async (): Promise<void> => {\n      stopped = true;\n      for (const controller of controllers) controller.abort();\n      for (const peer of sockets.clients) peer.terminate();\n      await new Promise<void>((resolve) => sockets.close(() => resolve()));\n    },\n  };\n};\n\nimport type { ChannelSocketOpenResult } from '@finalai/agent-provider/local-channel-socket';\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/modules/cli/cli.d.mts

@@ -0,0 +1,16 @@
+import type { FetchIface } from "../agent-client/http.mjs";
+import { type ImportModule } from "./conformance.mjs";
+import { type ListFiles } from "./files.mjs";
+import type { OutputIface } from "./output.mjs";
+export declare const DEFAULT_AGENTS_HOST = "https://agent-session.final.ai/api";
+export interface AgentsCliDepsIface {
+    argv: string[];
+    env: Record<string, string | undefined>;
+    cwd: string;
+    output: OutputIface;
+    fetch?: FetchIface;
+    listFiles?: ListFiles;
+    signal?: AbortSignal;
+    importModule?: ImportModule;
+}
+export declare const runAgentsCommand: (deps: AgentsCliDepsIface) => Promise<number>;