@finalai/agents 0.8.0

package/README.md

@@ -0,0 +1,30 @@
+# @finalai/agents
+
+SDK for defining, publishing, and using agents. Authoring helpers are implemented in
+`@finalai/agent-definition`; Final-specific bindings come from
+`@finalai/final-agent-provider`.
+
+```ts
+import { defineAgent } from '@finalai/agents';
+import { serverlessPi } from '@finalai/agents/harnesses';
+
+export default defineAgent({
+  name: 'Assistant',
+  harness: serverlessPi({
+    credentials: { payer: 'agent-owner', tryInOrder: [{ kind: 'platform' }] },
+  }),
+});
+```
+
+Use `@finalai/agents/client` for definitions, sessions, conversations, approvals,
+attachments, schedules, sandbox access, and realtime. Use `final-agents --help`
+for CLI commands. Compilation requires Node 26 and ships its assets through
+`agent-definition`.
+
+Credential-chain declarations select which credentials an agent may use and in
+which order. Set the payer policy explicitly in the harness configuration.
+
+For custom provider implementations, import contracts from `@finalai/agent-provider`,
+sandbox adapters from `@finalai/agent-provider/sandbox`, and conformance tools from
+`@finalai/agent-provider/conformance`. Run a harness check with
+`final-agents conformance ./harness.ts`.

package/dist/modules/agent-client/acp-frames.d.mts

@@ -0,0 +1,19 @@
+import { type AcpFrameEventIface, type AcpSessionUpdateParamsIface } from '@finalai/agent-protocol/agent-platform';
+export type AcpSessionUpdateIface = AcpSessionUpdateParamsIface['update'];
+/** The `session/update` payload of an agent frame, or null for any other frame. */
+export declare const sessionUpdateOf: (event: AcpFrameEventIface) => AcpSessionUpdateIface | null;
+/** Text carried by an `agent_message_chunk` / `agent_message` update. */
+export declare const textOf: (update: AcpSessionUpdateIface) => string;
+export interface TurnEndIface {
+    stopReason: string | null;
+}
+/** A `state_update` to `idle` ends the turn (ACP v2); returns its stop reason. */
+export declare const turnEndOf: (event: AcpFrameEventIface) => TurnEndIface | null;
+/** Whether the frame is the user-message update ACP emits for the accepted prompt `messageId`. */
+export declare const isUserMessageFor: (event: AcpFrameEventIface, messageId: string) => boolean;
+export interface TextCollectorIface {
+    add: (event: AcpFrameEventIface) => void;
+    text: () => string;
+}
+/** Accumulates visible agent text across chunks and full messages, per message id. */
+export declare const createTextCollector: () => TextCollectorIface;

package/dist/modules/agent-client/acp-frames.mjs

@@ -0,0 +1,49 @@
+import {
+  AcpFrameDirection,
+  acpSessionUpdateParamsSchema
+} from "@finalai/agent-protocol/agent-platform";
+const SESSION_UPDATE = "session/update";
+const sessionUpdateOf = (event) => {
+  if (event.frame.method !== SESSION_UPDATE) return null;
+  const parsed = acpSessionUpdateParamsSchema.safeParse(event.frame.params);
+  return parsed.success ? parsed.data.update : null;
+};
+const textOf = (update) => {
+  const content = update.content;
+  if (content == null) return "";
+  const blocks = Array.isArray(content) ? content : [content];
+  return blocks.map((block) => block.type === "text" ? block.text ?? "" : "").join("");
+};
+const turnEndOf = (event) => {
+  if (event.direction !== AcpFrameDirection.AgentToClient) return null;
+  const update = sessionUpdateOf(event);
+  if (update?.sessionUpdate !== "state_update" || update.state !== "idle") return null;
+  return { stopReason: update.stopReason ?? null };
+};
+const isUserMessageFor = (event, messageId) => {
+  const update = sessionUpdateOf(event);
+  return update != null && (update.sessionUpdate === "user_message" || update.sessionUpdate === "user_message_chunk") && update.messageId === messageId;
+};
+const createTextCollector = () => {
+  const order = [];
+  const byMessage = /* @__PURE__ */ new Map();
+  const add = (event) => {
+    const update = sessionUpdateOf(event);
+    if (update == null) return;
+    const chunk = update.sessionUpdate === "agent_message_chunk";
+    if (!chunk && update.sessionUpdate !== "agent_message") return;
+    if (!chunk && update.content == null) return;
+    const key = update.messageId ?? "";
+    if (!byMessage.has(key)) order.push(key);
+    byMessage.set(key, chunk ? `${byMessage.get(key) ?? ""}${textOf(update)}` : textOf(update));
+  };
+  return { add, text: () => order.map((key) => byMessage.get(key) ?? "").join("") };
+};
+export {
+  createTextCollector,
+  isUserMessageFor,
+  sessionUpdateOf,
+  textOf,
+  turnEndOf
+};
+//# sourceMappingURL=acp-frames.mjs.map

package/dist/modules/agent-client/acp-frames.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/acp-frames.ts"],
+  "sourcesContent": ["import {\n  AcpFrameDirection,\n  acpSessionUpdateParamsSchema,\n  type AcpFrameEventIface,\n  type AcpSessionUpdateParamsIface,\n} from '@finalai/agent-protocol/agent-platform';\n\nexport type AcpSessionUpdateIface = AcpSessionUpdateParamsIface['update'];\n\nconst SESSION_UPDATE = 'session/update';\n\n/** The `session/update` payload of an agent frame, or null for any other frame. */\nexport const sessionUpdateOf = (event: AcpFrameEventIface): AcpSessionUpdateIface | null => {\n  if (event.frame.method !== SESSION_UPDATE) return null;\n  const parsed = acpSessionUpdateParamsSchema.safeParse(event.frame.params);\n  return parsed.success ? parsed.data.update : null;\n};\n\n/** Text carried by an `agent_message_chunk` / `agent_message` update. */\nexport const textOf = (update: AcpSessionUpdateIface): string => {\n  const content = update.content;\n  if (content == null) return '';\n  const blocks = Array.isArray(content) ? content : [content];\n  return blocks.map((block) => (block.type === 'text' ? (block.text ?? '') : '')).join('');\n};\n\nexport interface TurnEndIface {\n  stopReason: string | null;\n}\n\n/** A `state_update` to `idle` ends the turn (ACP v2); returns its stop reason. */\nexport const turnEndOf = (event: AcpFrameEventIface): TurnEndIface | null => {\n  if (event.direction !== AcpFrameDirection.AgentToClient) return null;\n  const update = sessionUpdateOf(event);\n  if (update?.sessionUpdate !== 'state_update' || update.state !== 'idle') return null;\n  return { stopReason: update.stopReason ?? null };\n};\n\n/** Whether the frame is the user-message update ACP emits for the accepted prompt `messageId`. */\nexport const isUserMessageFor = (event: AcpFrameEventIface, messageId: string): boolean => {\n  const update = sessionUpdateOf(event);\n  return (\n    update != null &&\n    (update.sessionUpdate === 'user_message' || update.sessionUpdate === 'user_message_chunk') &&\n    update.messageId === messageId\n  );\n};\n\nexport interface TextCollectorIface {\n  add: (event: AcpFrameEventIface) => void;\n  text: () => string;\n}\n\n/** Accumulates visible agent text across chunks and full messages, per message id. */\nexport const createTextCollector = (): TextCollectorIface => {\n  const order: string[] = [];\n  const byMessage = new Map<string, string>();\n  const add = (event: AcpFrameEventIface): void => {\n    const update = sessionUpdateOf(event);\n    if (update == null) return;\n    const chunk = update.sessionUpdate === 'agent_message_chunk';\n    if (!chunk && update.sessionUpdate !== 'agent_message') return;\n    if (!chunk && update.content == null) return;\n    const key = update.messageId ?? '';\n    if (!byMessage.has(key)) order.push(key);\n    byMessage.set(key, chunk ? `${byMessage.get(key) ?? ''}${textOf(update)}` : textOf(update));\n  };\n  return { add, text: () => order.map((key) => byMessage.get(key) ?? '').join('') };\n};\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAGK;AAIP,MAAM,iBAAiB;AAGhB,MAAM,kBAAkB,CAAC,UAA4D;AAC1F,MAAI,MAAM,MAAM,WAAW,eAAgB,QAAO;AAClD,QAAM,SAAS,6BAA6B,UAAU,MAAM,MAAM,MAAM;AACxE,SAAO,OAAO,UAAU,OAAO,KAAK,SAAS;AAC/C;AAGO,MAAM,SAAS,CAAC,WAA0C;AAC/D,QAAM,UAAU,OAAO;AACvB,MAAI,WAAW,KAAM,QAAO;AAC5B,QAAM,SAAS,MAAM,QAAQ,OAAO,IAAI,UAAU,CAAC,OAAO;AAC1D,SAAO,OAAO,IAAI,CAAC,UAAW,MAAM,SAAS,SAAU,MAAM,QAAQ,KAAM,EAAG,EAAE,KAAK,EAAE;AACzF;AAOO,MAAM,YAAY,CAAC,UAAmD;AAC3E,MAAI,MAAM,cAAc,kBAAkB,cAAe,QAAO;AAChE,QAAM,SAAS,gBAAgB,KAAK;AACpC,MAAI,QAAQ,kBAAkB,kBAAkB,OAAO,UAAU,OAAQ,QAAO;AAChF,SAAO,EAAE,YAAY,OAAO,cAAc,KAAK;AACjD;AAGO,MAAM,mBAAmB,CAAC,OAA2B,cAA+B;AACzF,QAAM,SAAS,gBAAgB,KAAK;AACpC,SACE,UAAU,SACT,OAAO,kBAAkB,kBAAkB,OAAO,kBAAkB,yBACrE,OAAO,cAAc;AAEzB;AAQO,MAAM,sBAAsB,MAA0B;AAC3D,QAAM,QAAkB,CAAC;AACzB,QAAM,YAAY,oBAAI,IAAoB;AAC1C,QAAM,MAAM,CAAC,UAAoC;AAC/C,UAAM,SAAS,gBAAgB,KAAK;AACpC,QAAI,UAAU,KAAM;AACpB,UAAM,QAAQ,OAAO,kBAAkB;AACvC,QAAI,CAAC,SAAS,OAAO,kBAAkB,gBAAiB;AACxD,QAAI,CAAC,SAAS,OAAO,WAAW,KAAM;AACtC,UAAM,MAAM,OAAO,aAAa;AAChC,QAAI,CAAC,UAAU,IAAI,GAAG,EAAG,OAAM,KAAK,GAAG;AACvC,cAAU,IAAI,KAAK,QAAQ,GAAG,UAAU,IAAI,GAAG,KAAK,EAAE,GAAG,OAAO,MAAM,CAAC,KAAK,OAAO,MAAM,CAAC;AAAA,EAC5F;AACA,SAAO,EAAE,KAAK,MAAM,MAAM,MAAM,IAAI,CAAC,QAAQ,UAAU,IAAI,GAAG,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE;AAClF;",
+  "names": []
+}

package/dist/modules/agent-client/acp.d.mts

@@ -0,0 +1,43 @@
+import type { ClientApp, ClientConnection } from '@agentclientprotocol/sdk/experimental/v2';
+import type { WebSocketConstructor } from '@agentclientprotocol/sdk/experimental/ws-client';
+import type { SignalOptionsIface } from "./context.mjs";
+import { type CreateHttpOptionsIface, type HttpIface } from "./http.mjs";
+/** How the WebSocket upgrade authenticates. */
+export declare enum AcpAuthMode {
+    /** The client's authorization header (Node and other runtimes that can set headers). */
+    Headers = "headers",
+    /**
+     * A single-use ticket minted over HTTP (`POST /v1/acp/tickets`) and offered
+     * as a subprotocol: for browsers, whose WebSocket cannot send headers.
+     */
+    Ticket = "ticket"
+}
+export interface AcpConnectArgsIface extends SignalOptionsIface {
+    /** Agent slug or id; may instead be given in `session/new` `_meta`. */
+    agent?: string;
+    /** The ClientApp to connect; defaults to an app with no handlers. */
+    app?: ClientApp;
+    /** WebSocket constructor for Node (for example `ws.WebSocket`); browsers use the global. */
+    WebSocket?: WebSocketConstructor;
+    /** Defaults to `Ticket` for cookie-authenticated (browser) clients, `Headers` otherwise. */
+    authMode?: AcpAuthMode;
+}
+export interface AcpApiIface {
+    connect: (args?: AcpConnectArgsIface) => Promise<ClientConnection>;
+}
+export declare const acpWebSocketUrl: (args: {
+    host: URL;
+    agent?: string;
+    endpoint?: string;
+}) => string;
+export interface AcpTransportIface {
+    url: string;
+    headers: Record<string, string>;
+    protocols: string[] | undefined;
+}
+/** Where and how `connect` opens the socket; exported for tests. */
+export declare const resolveAcpTransport: (http: HttpIface, args: AcpConnectArgsIface | undefined) => Promise<AcpTransportIface>;
+export declare const createAcpApi: (context: {
+    http: HttpIface;
+}) => AcpApiIface;
+export declare const createAcpClient: (options: CreateHttpOptionsIface) => AcpApiIface;

package/dist/modules/agent-client/acp.mjs

@@ -0,0 +1,76 @@
+import {
+  ACP_TICKET_SUBPROTOCOL_PREFIX,
+  ACP_WS_SUBPROTOCOL,
+  acpTicketRequestSchema,
+  acpTicketSchema
+} from "@finalai/agent-protocol/agent-platform";
+import { createHttp, HttpMethod } from "./http.mjs";
+var AcpAuthMode = /* @__PURE__ */ ((AcpAuthMode2) => {
+  AcpAuthMode2["Headers"] = "headers";
+  AcpAuthMode2["Ticket"] = "ticket";
+  return AcpAuthMode2;
+})(AcpAuthMode || {});
+const acpWebSocketUrl = (args) => {
+  const url = args.endpoint == null ? new URL("/acp/ws", args.host) : new URL(args.endpoint);
+  url.protocol = url.protocol === "http:" || url.protocol === "ws:" ? "ws:" : "wss:";
+  if (args.agent != null) url.searchParams.set("agent", args.agent);
+  return url.toString();
+};
+const resolveAcpTransport = async (http, args) => {
+  const mode = args?.authMode ?? (http.usesCookies ? "ticket" /* Ticket */ : "headers" /* Headers */);
+  if (mode === "headers" /* Headers */) {
+    return {
+      url: acpWebSocketUrl({ host: http.url(""), agent: args?.agent }),
+      headers: await http.headers(),
+      protocols: void 0
+    };
+  }
+  const ticket = await http.request({
+    method: HttpMethod.Post,
+    path: "/v1/acp/tickets",
+    body: { schema: acpTicketRequestSchema, value: { agent: args?.agent } },
+    response: acpTicketSchema,
+    signal: args?.signal
+  });
+  return {
+    url: acpWebSocketUrl({
+      host: http.url(""),
+      agent: args?.agent,
+      endpoint: ticket.url ?? void 0
+    }),
+    headers: {},
+    protocols: [ACP_WS_SUBPROTOCOL, `${ACP_TICKET_SUBPROTOCOL_PREFIX}${ticket.ticket}`]
+  };
+};
+const createAcpApi = (context) => ({
+  connect: async (args) => {
+    const [{ client }, { createWebSocketStream }] = await Promise.all([
+      import("@agentclientprotocol/sdk/experimental/v2"),
+      import("@agentclientprotocol/sdk/experimental/ws-client")
+    ]);
+    const transport = await resolveAcpTransport(context.http, args);
+    const stream = createWebSocketStream(transport.url, {
+      headers: transport.headers,
+      protocols: transport.protocols,
+      // The ticket is the credential; the session service has no cookie auth.
+      cookies: "omit",
+      WebSocket: args?.WebSocket
+    });
+    const connection = (args?.app ?? client({ name: "@finalai/agents" })).connect(stream);
+    const signal = args?.signal;
+    if (signal != null) {
+      if (signal.aborted) connection.close(signal.reason);
+      else signal.addEventListener("abort", () => connection.close(signal.reason), { once: true });
+    }
+    return connection;
+  }
+});
+const createAcpClient = (options) => createAcpApi({ http: createHttp(options) });
+export {
+  AcpAuthMode,
+  acpWebSocketUrl,
+  createAcpApi,
+  createAcpClient,
+  resolveAcpTransport
+};
+//# sourceMappingURL=acp.mjs.map

package/dist/modules/agent-client/acp.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/acp.ts"],
+  "sourcesContent": ["import type {\n  AnyWireMessage,\n  ClientApp,\n  ClientConnection,\n} from '@agentclientprotocol/sdk/experimental/v2';\nimport type { WebSocketConstructor } from '@agentclientprotocol/sdk/experimental/ws-client';\nimport {\n  ACP_TICKET_SUBPROTOCOL_PREFIX,\n  ACP_WS_SUBPROTOCOL,\n  acpTicketRequestSchema,\n  acpTicketSchema,\n} from '@finalai/agent-protocol/agent-platform';\nimport type { SignalOptionsIface } from \"./context.mjs\";\nimport { createHttp, HttpMethod, type CreateHttpOptionsIface, type HttpIface } from \"./http.mjs\";\n\n// ACP-native access: the session service serves a standard ACP v2 agent at\n// `/acp/ws`. Callers bring a ClientApp with their handlers (session updates,\n// permission requests); `?agent=` is the agent a plain `session/new` opens,\n// and `_meta[\"final.ai\"].agent` names one per session.\n\n/** How the WebSocket upgrade authenticates. */\nexport enum AcpAuthMode {\n  /** The client's authorization header (Node and other runtimes that can set headers). */\n  Headers = 'headers',\n  /**\n   * A single-use ticket minted over HTTP (`POST /v1/acp/tickets`) and offered\n   * as a subprotocol: for browsers, whose WebSocket cannot send headers.\n   */\n  Ticket = 'ticket',\n}\n\nexport interface AcpConnectArgsIface extends SignalOptionsIface {\n  /** Agent slug or id; may instead be given in `session/new` `_meta`. */\n  agent?: string;\n  /** The ClientApp to connect; defaults to an app with no handlers. */\n  app?: ClientApp;\n  /** WebSocket constructor for Node (for example `ws.WebSocket`); browsers use the global. */\n  WebSocket?: WebSocketConstructor;\n  /** Defaults to `Ticket` for cookie-authenticated (browser) clients, `Headers` otherwise. */\n  authMode?: AcpAuthMode;\n}\n\nexport interface AcpApiIface {\n  connect: (args?: AcpConnectArgsIface) => Promise<ClientConnection>;\n}\n\nexport const acpWebSocketUrl = (args: { host: URL; agent?: string; endpoint?: string }): string => {\n  // ACP is served at the session service's origin, not under the API prefix (a\n  // ticket names it, which matters behind console-server's HTTP-only proxy).\n  const url = args.endpoint == null ? new URL('/acp/ws', args.host) : new URL(args.endpoint);\n  url.protocol = url.protocol === 'http:' || url.protocol === 'ws:' ? 'ws:' : 'wss:';\n  if (args.agent != null) url.searchParams.set('agent', args.agent);\n  return url.toString();\n};\n\nexport interface AcpTransportIface {\n  url: string;\n  headers: Record<string, string>;\n  protocols: string[] | undefined;\n}\n\n/** Where and how `connect` opens the socket; exported for tests. */\nexport const resolveAcpTransport = async (\n  http: HttpIface,\n  args: AcpConnectArgsIface | undefined,\n): Promise<AcpTransportIface> => {\n  const mode = args?.authMode ?? (http.usesCookies ? AcpAuthMode.Ticket : AcpAuthMode.Headers);\n  if (mode === AcpAuthMode.Headers) {\n    return {\n      url: acpWebSocketUrl({ host: http.url(''), agent: args?.agent }),\n      headers: await http.headers(),\n      protocols: undefined,\n    };\n  }\n  const ticket = await http.request({\n    method: HttpMethod.Post,\n    path: '/v1/acp/tickets',\n    body: { schema: acpTicketRequestSchema, value: { agent: args?.agent } },\n    response: acpTicketSchema,\n    signal: args?.signal,\n  });\n  return {\n    url: acpWebSocketUrl({\n      host: http.url(''),\n      agent: args?.agent,\n      endpoint: ticket.url ?? undefined,\n    }),\n    headers: {},\n    protocols: [ACP_WS_SUBPROTOCOL, `${ACP_TICKET_SUBPROTOCOL_PREFIX}${ticket.ticket}`],\n  };\n};\n\nexport const createAcpApi = (context: { http: HttpIface }): AcpApiIface => ({\n  connect: async (args) => {\n    // The ACP SDK loads on first use: bundlers that split code keep it out of\n    // HTTP-only pages.\n    const [{ client }, { createWebSocketStream }] = await Promise.all([\n      import('@agentclientprotocol/sdk/experimental/v2'),\n      import('@agentclientprotocol/sdk/experimental/ws-client'),\n    ]);\n    const transport = await resolveAcpTransport(context.http, args);\n    const stream = createWebSocketStream<AnyWireMessage>(transport.url, {\n      headers: transport.headers,\n      protocols: transport.protocols,\n      // The ticket is the credential; the session service has no cookie auth.\n      cookies: 'omit',\n      WebSocket: args?.WebSocket,\n    });\n    const connection = (args?.app ?? client({ name: '@finalai/agents' })).connect(stream);\n    const signal = args?.signal;\n    if (signal != null) {\n      if (signal.aborted) connection.close(signal.reason);\n      else signal.addEventListener('abort', () => connection.close(signal.reason), { once: true });\n    }\n    return connection;\n  },\n});\n\n// `client.acp` without the rest of the client (`@finalai/agents/client/acp`).\nexport const createAcpClient = (options: CreateHttpOptionsIface): AcpApiIface =>\n  createAcpApi({ http: createHttp(options) });\n"],
+  "mappings": "AAMA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,SAAS,YAAY,kBAA+D;AAQ7E,IAAK,cAAL,kBAAKA,iBAAL;AAEL,EAAAA,aAAA,aAAU;AAKV,EAAAA,aAAA,YAAS;AAPC,SAAAA;AAAA,GAAA;AAyBL,MAAM,kBAAkB,CAAC,SAAmE;AAGjG,QAAM,MAAM,KAAK,YAAY,OAAO,IAAI,IAAI,WAAW,KAAK,IAAI,IAAI,IAAI,IAAI,KAAK,QAAQ;AACzF,MAAI,WAAW,IAAI,aAAa,WAAW,IAAI,aAAa,QAAQ,QAAQ;AAC5E,MAAI,KAAK,SAAS,KAAM,KAAI,aAAa,IAAI,SAAS,KAAK,KAAK;AAChE,SAAO,IAAI,SAAS;AACtB;AASO,MAAM,sBAAsB,OACjC,MACA,SAC+B;AAC/B,QAAM,OAAO,MAAM,aAAa,KAAK,cAAc,wBAAqB;AACxE,MAAI,SAAS,yBAAqB;AAChC,WAAO;AAAA,MACL,KAAK,gBAAgB,EAAE,MAAM,KAAK,IAAI,EAAE,GAAG,OAAO,MAAM,MAAM,CAAC;AAAA,MAC/D,SAAS,MAAM,KAAK,QAAQ;AAAA,MAC5B,WAAW;AAAA,IACb;AAAA,EACF;AACA,QAAM,SAAS,MAAM,KAAK,QAAQ;AAAA,IAChC,QAAQ,WAAW;AAAA,IACnB,MAAM;AAAA,IACN,MAAM,EAAE,QAAQ,wBAAwB,OAAO,EAAE,OAAO,MAAM,MAAM,EAAE;AAAA,IACtE,UAAU;AAAA,IACV,QAAQ,MAAM;AAAA,EAChB,CAAC;AACD,SAAO;AAAA,IACL,KAAK,gBAAgB;AAAA,MACnB,MAAM,KAAK,IAAI,EAAE;AAAA,MACjB,OAAO,MAAM;AAAA,MACb,UAAU,OAAO,OAAO;AAAA,IAC1B,CAAC;AAAA,IACD,SAAS,CAAC;AAAA,IACV,WAAW,CAAC,oBAAoB,GAAG,6BAA6B,GAAG,OAAO,MAAM,EAAE;AAAA,EACpF;AACF;AAEO,MAAM,eAAe,CAAC,aAA+C;AAAA,EAC1E,SAAS,OAAO,SAAS;AAGvB,UAAM,CAAC,EAAE,OAAO,GAAG,EAAE,sBAAsB,CAAC,IAAI,MAAM,QAAQ,IAAI;AAAA,MAChE,OAAO,0CAA0C;AAAA,MACjD,OAAO,iDAAiD;AAAA,IAC1D,CAAC;AACD,UAAM,YAAY,MAAM,oBAAoB,QAAQ,MAAM,IAAI;AAC9D,UAAM,SAAS,sBAAsC,UAAU,KAAK;AAAA,MAClE,SAAS,UAAU;AAAA,MACnB,WAAW,UAAU;AAAA;AAAA,MAErB,SAAS;AAAA,MACT,WAAW,MAAM;AAAA,IACnB,CAAC;AACD,UAAM,cAAc,MAAM,OAAO,OAAO,EAAE,MAAM,kBAAkB,CAAC,GAAG,QAAQ,MAAM;AACpF,UAAM,SAAS,MAAM;AACrB,QAAI,UAAU,MAAM;AAClB,UAAI,OAAO,QAAS,YAAW,MAAM,OAAO,MAAM;AAAA,UAC7C,QAAO,iBAAiB,SAAS,MAAM,WAAW,MAAM,OAAO,MAAM,GAAG,EAAE,MAAM,KAAK,CAAC;AAAA,IAC7F;AACA,WAAO;AAAA,EACT;AACF;AAGO,MAAM,kBAAkB,CAAC,YAC9B,aAAa,EAAE,MAAM,WAAW,OAAO,EAAE,CAAC;",
+  "names": ["AcpAuthMode"]
+}

package/dist/modules/agent-client/async-queue.d.mts

@@ -0,0 +1,10 @@
+export interface AsyncQueueIface<Value> {
+    push: (value: Value) => void;
+    end: () => void;
+    fail: (cause: unknown) => void;
+    readonly closed: () => boolean;
+    iterator: AsyncIterableIterator<Value>;
+}
+export declare const createAsyncQueue: <Value>(cleanup: () => void) => AsyncQueueIface<Value>;
+/** Fails the queue with the signal's reason when it aborts; returns the detach function. */
+export declare const failOnAbort: <Value>(queue: AsyncQueueIface<Value>, signal: AbortSignal | undefined) => (() => void);

package/dist/modules/agent-client/async-queue.mjs

@@ -0,0 +1,66 @@
+const DONE = { done: true, value: void 0 };
+const createAsyncQueue = (cleanup) => {
+  const values = [];
+  const waiters = [];
+  let finished = false;
+  let failure = null;
+  let cleanedUp = false;
+  const runCleanup = () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    cleanup();
+  };
+  const push = (value) => {
+    if (finished) return;
+    const waiter = waiters.shift();
+    if (waiter != null) waiter.resolve({ done: false, value });
+    else values.push(value);
+  };
+  const end = () => {
+    if (finished) return;
+    finished = true;
+    for (const waiter of waiters.splice(0)) waiter.resolve(DONE);
+    runCleanup();
+  };
+  const fail = (cause) => {
+    if (finished) return;
+    finished = true;
+    failure = { cause };
+    values.length = 0;
+    for (const waiter of waiters.splice(0)) waiter.reject(cause);
+    runCleanup();
+  };
+  const iterator = {
+    next: () => {
+      const value = values.shift();
+      if (value !== void 0) return Promise.resolve({ done: false, value });
+      if (failure != null) return Promise.reject(failure.cause);
+      if (finished) return Promise.resolve(DONE);
+      return new Promise((resolve, reject) => waiters.push({ resolve, reject }));
+    },
+    return: () => {
+      values.length = 0;
+      end();
+      return Promise.resolve(DONE);
+    },
+    [Symbol.asyncIterator]: () => iterator
+  };
+  return { push, end, fail, closed: () => finished, iterator };
+};
+const failOnAbort = (queue, signal) => {
+  if (signal == null) return () => {
+  };
+  if (signal.aborted) {
+    queue.fail(signal.reason);
+    return () => {
+    };
+  }
+  const onAbort = () => queue.fail(signal.reason);
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+};
+export {
+  createAsyncQueue,
+  failOnAbort
+};
+//# sourceMappingURL=async-queue.mjs.map

package/dist/modules/agent-client/async-queue.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/async-queue.ts"],
+  "sourcesContent": ["// A push-to-pull bridge: producers push values, one consumer iterates them.\n// `cleanup` runs once, when the producer ends or fails or the consumer stops\n// (break, return, abort).\n\nexport interface AsyncQueueIface<Value> {\n  push: (value: Value) => void;\n  end: () => void;\n  fail: (cause: unknown) => void;\n  readonly closed: () => boolean;\n  iterator: AsyncIterableIterator<Value>;\n}\n\ninterface WaiterIface<Value> {\n  resolve: (result: IteratorResult<Value, undefined>) => void;\n  reject: (cause: unknown) => void;\n}\n\nconst DONE = { done: true, value: undefined } as const;\n\nexport const createAsyncQueue = <Value>(cleanup: () => void): AsyncQueueIface<Value> => {\n  const values: Value[] = [];\n  const waiters: WaiterIface<Value>[] = [];\n  let finished = false;\n  let failure: { cause: unknown } | null = null;\n  let cleanedUp = false;\n\n  const runCleanup = (): void => {\n    if (cleanedUp) return;\n    cleanedUp = true;\n    cleanup();\n  };\n\n  const push = (value: Value): void => {\n    if (finished) return;\n    const waiter = waiters.shift();\n    if (waiter != null) waiter.resolve({ done: false, value });\n    else values.push(value);\n  };\n\n  const end = (): void => {\n    if (finished) return;\n    finished = true;\n    for (const waiter of waiters.splice(0)) waiter.resolve(DONE);\n    runCleanup();\n  };\n\n  const fail = (cause: unknown): void => {\n    if (finished) return;\n    finished = true;\n    failure = { cause };\n    values.length = 0;\n    for (const waiter of waiters.splice(0)) waiter.reject(cause);\n    runCleanup();\n  };\n\n  const iterator: AsyncIterableIterator<Value> = {\n    next: (): Promise<IteratorResult<Value, undefined>> => {\n      const value = values.shift();\n      if (value !== undefined) return Promise.resolve({ done: false, value });\n      if (failure != null) return Promise.reject(failure.cause);\n      if (finished) return Promise.resolve(DONE);\n      return new Promise((resolve, reject) => waiters.push({ resolve, reject }));\n    },\n    return: (): Promise<IteratorResult<Value, undefined>> => {\n      values.length = 0;\n      end();\n      return Promise.resolve(DONE);\n    },\n    [Symbol.asyncIterator]: () => iterator,\n  };\n\n  return { push, end, fail, closed: () => finished, iterator };\n};\n\n/** Fails the queue with the signal's reason when it aborts; returns the detach function. */\nexport const failOnAbort = <Value>(\n  queue: AsyncQueueIface<Value>,\n  signal: AbortSignal | undefined,\n): (() => void) => {\n  if (signal == null) return () => {};\n  if (signal.aborted) {\n    queue.fail(signal.reason);\n    return () => {};\n  }\n  const onAbort = (): void => queue.fail(signal.reason);\n  signal.addEventListener('abort', onAbort, { once: true });\n  return () => signal.removeEventListener('abort', onAbort);\n};\n"],
+  "mappings": "AAiBA,MAAM,OAAO,EAAE,MAAM,MAAM,OAAO,OAAU;AAErC,MAAM,mBAAmB,CAAQ,YAAgD;AACtF,QAAM,SAAkB,CAAC;AACzB,QAAM,UAAgC,CAAC;AACvC,MAAI,WAAW;AACf,MAAI,UAAqC;AACzC,MAAI,YAAY;AAEhB,QAAM,aAAa,MAAY;AAC7B,QAAI,UAAW;AACf,gBAAY;AACZ,YAAQ;AAAA,EACV;AAEA,QAAM,OAAO,CAAC,UAAuB;AACnC,QAAI,SAAU;AACd,UAAM,SAAS,QAAQ,MAAM;AAC7B,QAAI,UAAU,KAAM,QAAO,QAAQ,EAAE,MAAM,OAAO,MAAM,CAAC;AAAA,QACpD,QAAO,KAAK,KAAK;AAAA,EACxB;AAEA,QAAM,MAAM,MAAY;AACtB,QAAI,SAAU;AACd,eAAW;AACX,eAAW,UAAU,QAAQ,OAAO,CAAC,EAAG,QAAO,QAAQ,IAAI;AAC3D,eAAW;AAAA,EACb;AAEA,QAAM,OAAO,CAAC,UAAyB;AACrC,QAAI,SAAU;AACd,eAAW;AACX,cAAU,EAAE,MAAM;AAClB,WAAO,SAAS;AAChB,eAAW,UAAU,QAAQ,OAAO,CAAC,EAAG,QAAO,OAAO,KAAK;AAC3D,eAAW;AAAA,EACb;AAEA,QAAM,WAAyC;AAAA,IAC7C,MAAM,MAAiD;AACrD,YAAM,QAAQ,OAAO,MAAM;AAC3B,UAAI,UAAU,OAAW,QAAO,QAAQ,QAAQ,EAAE,MAAM,OAAO,MAAM,CAAC;AACtE,UAAI,WAAW,KAAM,QAAO,QAAQ,OAAO,QAAQ,KAAK;AACxD,UAAI,SAAU,QAAO,QAAQ,QAAQ,IAAI;AACzC,aAAO,IAAI,QAAQ,CAAC,SAAS,WAAW,QAAQ,KAAK,EAAE,SAAS,OAAO,CAAC,CAAC;AAAA,IAC3E;AAAA,IACA,QAAQ,MAAiD;AACvD,aAAO,SAAS;AAChB,UAAI;AACJ,aAAO,QAAQ,QAAQ,IAAI;AAAA,IAC7B;AAAA,IACA,CAAC,OAAO,aAAa,GAAG,MAAM;AAAA,EAChC;AAEA,SAAO,EAAE,MAAM,KAAK,MAAM,QAAQ,MAAM,UAAU,SAAS;AAC7D;AAGO,MAAM,cAAc,CACzB,OACA,WACiB;AACjB,MAAI,UAAU,KAAM,QAAO,MAAM;AAAA,EAAC;AAClC,MAAI,OAAO,SAAS;AAClB,UAAM,KAAK,OAAO,MAAM;AACxB,WAAO,MAAM;AAAA,IAAC;AAAA,EAChB;AACA,QAAM,UAAU,MAAY,MAAM,KAAK,OAAO,MAAM;AACpD,SAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AACxD,SAAO,MAAM,OAAO,oBAAoB,SAAS,OAAO;AAC1D;",
+  "names": []
+}

package/dist/modules/agent-client/build.d.mts

@@ -0,0 +1,107 @@
+import { type AttachChannelBindingResponseIface, type CommitDefinitionRequestIface, type CommitResultIface, type CompatibilityReportIface, type CompileResultIface, type ComputerSetupGuideDetailIface, type ComputerSetupGuideIface, type ComputerSetupGuideVersionIface, type CreateDefinitionRequestIface, type CredentialPolicyPreviewIface, type DefinitionChannelIface, type DefinitionCloneUrlIface, type DefinitionFilesIface, type DefinitionIface, type PreviewCredentialPolicyRequestIface, type ProviderEntryIface, type PublishComputerSetupGuideRequestIface, type PublishResultIface, type RevisionDiffIface, type RevisionIface, type ScheduleIface, type ScheduleRunResultIface, type UpdateScheduleRequestIface } from '@finalai/agent-protocol/agent-platform';
+import { type ClientContextIface, type SignalOptionsIface } from "./context.mjs";
+export interface DefinitionRefIface extends SignalOptionsIface {
+    /** Definition id or slug. */
+    definition: string;
+}
+export interface DefinitionsApiIface {
+    /** Compiles a draft into an immutable test snapshot without publishing or activating schedules/channels. */
+    testRevision: (args: DefinitionRefIface & {
+        ref: string;
+    }) => Promise<RevisionIface>;
+    previewCredentialPolicy: (args: DefinitionRefIface & PreviewCredentialPolicyRequestIface) => Promise<CredentialPolicyPreviewIface>;
+    list: (options?: SignalOptionsIface & {
+        cursor?: string;
+        limit?: number;
+    }) => Promise<{
+        definitions: DefinitionIface[];
+        nextCursor: string | null;
+    }>;
+    create: (args: CreateDefinitionRequestIface & SignalOptionsIface) => Promise<DefinitionIface>;
+    get: (args: DefinitionRefIface) => Promise<DefinitionIface>;
+    /** Compiles the directory at `ref` server-side without publishing. */
+    compile: (args: DefinitionRefIface & {
+        ref: string;
+        harness?: string;
+    }) => Promise<CompileResultIface>;
+    commit: (args: DefinitionRefIface & CommitDefinitionRequestIface) => Promise<CommitResultIface>;
+    /** Compiles `ref`, stores a revision and makes it current. */
+    publish: (args: DefinitionRefIface & {
+        ref: string;
+        note?: string;
+    }) => Promise<PublishResultIface>;
+    /** The agent directory's files at `ref` (default branch when omitted). */
+    files: (args: DefinitionRefIface & {
+        ref?: string;
+    }) => Promise<DefinitionFilesIface>;
+    revisions: (args: DefinitionRefIface & {
+        cursor?: string;
+    }) => Promise<{
+        revisions: RevisionIface[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * What changed in the compiled manifest between two revisions (revision ids
+     * or numbers); `to` defaults to the current revision.
+     */
+    revisionDiff: (args: DefinitionRefIface & {
+        from: string | number;
+        to?: string | number;
+    }) => Promise<RevisionDiffIface>;
+    compatibility: (args: DefinitionRefIface & {
+        harness: string;
+        ref?: string;
+    }) => Promise<CompatibilityReportIface>;
+    /** The agent's live channel bindings, with the conversation each is attached to. */
+    channels: (args: DefinitionRefIface) => Promise<DefinitionChannelIface[]>;
+    /**
+     * Attaches a channel binding to a conversation the agent and the caller take
+     * part in (its events and bound-conversation schedules post there); null detaches.
+     */
+    attachChannel: (args: DefinitionRefIface & {
+        bindingId: string;
+        conversationId: string | null;
+    }) => Promise<AttachChannelBindingResponseIface>;
+    /**
+     * Archives the definition: it leaves listings, its schedules and channel
+     * bindings stop, and new sessions are refused. Its repository is kept.
+     */
+    archive: (args: DefinitionRefIface) => Promise<DefinitionIface>;
+    /**
+     * A short-lived, read-only git remote for a Final-hosted repository, for
+     * `git clone` (owners of personal agents, organization admins otherwise).
+     */
+    cloneUrl: (args: DefinitionRefIface) => Promise<DefinitionCloneUrlIface>;
+}
+export interface ProvidersApiIface {
+    list: (options?: SignalOptionsIface) => Promise<ProviderEntryIface[]>;
+}
+export interface ComputerSetupGuidesApiIface {
+    list: (options?: SignalOptionsIface) => Promise<ComputerSetupGuideIface[]>;
+    /** Guide by slug or id, with its versions. */
+    get: (ref: string, options?: SignalOptionsIface) => Promise<ComputerSetupGuideDetailIface>;
+    /** Publishes a new version (creating the guide on first publish). */
+    publish: (args: PublishComputerSetupGuideRequestIface & SignalOptionsIface) => Promise<{
+        guide: ComputerSetupGuideIface;
+        version: ComputerSetupGuideVersionIface;
+    }>;
+}
+export type ScheduleRef = {
+    scheduleId: string;
+} | {
+    agent: string;
+    key: string;
+};
+export interface SchedulesApiIface {
+    list: (options?: SignalOptionsIface & {
+        agent?: string;
+    }) => Promise<ScheduleIface[]>;
+    runNow: (args: ScheduleRef & SignalOptionsIface) => Promise<ScheduleRunResultIface>;
+    update: (args: {
+        scheduleId: string;
+    } & UpdateScheduleRequestIface & SignalOptionsIface) => Promise<ScheduleIface>;
+}
+export declare const createDefinitionsApi: ({ http }: ClientContextIface) => DefinitionsApiIface;
+export declare const createProvidersApi: ({ http }: ClientContextIface) => ProvidersApiIface;
+export declare const createComputerSetupGuidesApi: ({ http, }: ClientContextIface) => ComputerSetupGuidesApiIface;
+export declare const createSchedulesApi: ({ http }: ClientContextIface) => SchedulesApiIface;