@finalai/agents 0.11.0 → 0.12.0

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

@@ -0,0 +1,77 @@
+import { connectSandboxClient } from "@finalai/agent-provider/sandbox/client";
+import { frameChannelFromWebSocket } from "@finalai/agent-provider/sandbox/wire";
+import * as z from "zod";
+import { noChannelSource } from "./channels.mjs";
+import { clientError, ClientErrorCode } from "./errors.mjs";
+import { LOCAL_HOST_SUBPROTOCOL } from "./local-host-protocol.mjs";
+const agentValueSchema = z.custom(
+  (value) => typeof value === "object" && value != null && "require" in value && "name" in value,
+  "Not an agent: define it with defineAgent, or fetch it with project.agents.get"
+);
+const agentValueOf = (agent) => {
+  const value = agentValueSchema.safeParse(agent);
+  if (value.success) return value.data;
+  throw clientError({
+    message: value.error.issues[0]?.message ?? "Not an agent",
+    status: 0,
+    code: ClientErrorCode.InvalidRequest
+  });
+};
+const defaultAgentCodec = {
+  documentOf: async (agent) => (await import("@finalai/agent-definition")).documentOf(agentValueOf(agent)),
+  inProcessCodeOf: async (agent) => (await import("@finalai/agent-definition")).inProcessCodeOf(agentValueOf(agent))
+};
+const defaultChannelSourceOf = noChannelSource;
+const defaultLocalCompute = () => ({
+  sandbox: async () => {
+    const { createLocalSandbox } = await import("@finalai/final-agent-provider/sandboxes/local");
+    return createLocalSandbox({ root: globalThis.process.cwd() });
+  },
+  openSandbox: (endpoint) => connectSandboxClient({
+    url: endpoint.url,
+    token: endpoint.token,
+    expiresAt: endpoint.expiresAt
+  })
+});
+const defaultLocalHostDial = (http) => async (path, signal) => {
+  const url = http.url(path);
+  url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
+  const headers = await http.headers();
+  const { WebSocket } = await import("ws");
+  signal?.throwIfAborted();
+  const socket = new WebSocket(url, [LOCAL_HOST_SUBPROTOCOL], { headers });
+  let tcp = null;
+  let referenced = true;
+  socket.on("upgrade", (response) => {
+    tcp = response.socket;
+    if (!referenced) tcp.unref();
+  });
+  const { channel, opened } = frameChannelFromWebSocket(socket);
+  const onAbort = () => socket.terminate();
+  signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    await opened;
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+  }
+  return {
+    ...channel,
+    keepAlive: {
+      ref: () => {
+        referenced = true;
+        tcp?.ref();
+      },
+      unref: () => {
+        referenced = false;
+        tcp?.unref();
+      }
+    }
+  };
+};
+export {
+  defaultAgentCodec,
+  defaultChannelSourceOf,
+  defaultLocalCompute,
+  defaultLocalHostDial
+};
+//# sourceMappingURL=defaults.mjs.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/defaults.ts"],
+  "sourcesContent": ["import type { AgentIface } from '@finalai/agent-definition';\nimport { connectSandboxClient } from '@finalai/agent-provider/sandbox/client';\nimport { frameChannelFromWebSocket } from '@finalai/agent-provider/sandbox/wire';\nimport * as z from 'zod';\nimport type { AgentValueCodecIface } from \"./agent-input.mjs\";\nimport { noChannelSource, type ChannelSourceOf } from \"./channels.mjs\";\nimport { clientError, ClientErrorCode } from \"./errors.mjs\";\nimport type { HttpIface } from \"./http.mjs\";\nimport { LOCAL_HOST_SUBPROTOCOL } from \"./local-host-protocol.mjs\";\nimport type { LocalComputeIface, LocalHostSocketIface } from \"./local-host.mjs\";\n\n// What `createClient` uses unless a seam replaces it.\n\nconst agentValueSchema = z.custom<AgentIface>(\n  (value) => typeof value === 'object' && value != null && 'require' in value && 'name' in value,\n  'Not an agent: define it with defineAgent, or fetch it with project.agents.get',\n);\n\nconst agentValueOf = (agent: object): AgentIface => {\n  const value = agentValueSchema.safeParse(agent);\n  if (value.success) return value.data;\n  throw clientError({\n    message: value.error.issues[0]?.message ?? 'Not an agent',\n    status: 0,\n    code: ClientErrorCode.InvalidRequest,\n  });\n};\n\n// Loaded on first use, so browser bundles of the client leave the authoring\n// code (and its source parser) out until an agent value is started.\nexport const defaultAgentCodec: AgentValueCodecIface = {\n  documentOf: async (agent) =>\n    (await import('@finalai/agent-definition')).documentOf(agentValueOf(agent)),\n  inProcessCodeOf: async (agent) =>\n    (await import('@finalai/agent-definition')).inProcessCodeOf(agentValueOf(agent)),\n};\n\nexport const defaultChannelSourceOf: ChannelSourceOf = noChannelSource;\n\n// The model's files and shell are this process's working directory, as for a\n// coding agent run on this machine. Loaded on use: it needs Node.\nexport const defaultLocalCompute = (): LocalComputeIface => ({\n  sandbox: async () => {\n    const { createLocalSandbox } = await import('@finalai/final-agent-provider/sandboxes/local');\n    return createLocalSandbox({ root: globalThis.process.cwd() });\n  },\n  openSandbox: (endpoint) =>\n    connectSandboxClient({\n      url: endpoint.url,\n      token: endpoint.token,\n      expiresAt: endpoint.expiresAt,\n    }),\n});\n\n// The local host socket is dialed from Node with the client's own headers. It\n// keeps the process alive only while the host starts or is in use (see\n// LocalHostKeepAliveIface), so a script that is done exits and the platform\n// reports its tools and compute as unavailable.\nexport const defaultLocalHostDial =\n  (http: HttpIface) =>\n  async (path: string, signal?: AbortSignal): Promise<LocalHostSocketIface> => {\n    const url = http.url(path);\n    url.protocol = url.protocol === 'http:' ? 'ws:' : 'wss:';\n    const headers = await http.headers();\n    const { WebSocket } = await import('ws');\n    signal?.throwIfAborted();\n    const socket = new WebSocket(url, [LOCAL_HOST_SUBPROTOCOL], { headers });\n    let tcp: { ref: () => unknown; unref: () => unknown } | null = null;\n    let referenced = true;\n    socket.on('upgrade', (response) => {\n      tcp = response.socket;\n      if (!referenced) tcp.unref();\n    });\n    const { channel, opened } = frameChannelFromWebSocket(socket);\n    // Aborting while the socket opens tears it down, which rejects `opened`.\n    const onAbort = () => socket.terminate();\n    signal?.addEventListener('abort', onAbort, { once: true });\n    try {\n      await opened;\n    } finally {\n      signal?.removeEventListener('abort', onAbort);\n    }\n    return {\n      ...channel,\n      keepAlive: {\n        ref: () => {\n          referenced = true;\n          tcp?.ref();\n        },\n        unref: () => {\n          referenced = false;\n          tcp?.unref();\n        },\n      },\n    };\n  };\n"],
+  "mappings": "AACA,SAAS,4BAA4B;AACrC,SAAS,iCAAiC;AAC1C,YAAY,OAAO;AAEnB,SAAS,uBAA6C;AACtD,SAAS,aAAa,uBAAuB;AAE7C,SAAS,8BAA8B;AAKvC,MAAM,mBAAmB,EAAE;AAAA,EACzB,CAAC,UAAU,OAAO,UAAU,YAAY,SAAS,QAAQ,aAAa,SAAS,UAAU;AAAA,EACzF;AACF;AAEA,MAAM,eAAe,CAAC,UAA8B;AAClD,QAAM,QAAQ,iBAAiB,UAAU,KAAK;AAC9C,MAAI,MAAM,QAAS,QAAO,MAAM;AAChC,QAAM,YAAY;AAAA,IAChB,SAAS,MAAM,MAAM,OAAO,CAAC,GAAG,WAAW;AAAA,IAC3C,QAAQ;AAAA,IACR,MAAM,gBAAgB;AAAA,EACxB,CAAC;AACH;AAIO,MAAM,oBAA0C;AAAA,EACrD,YAAY,OAAO,WAChB,MAAM,OAAO,2BAA2B,GAAG,WAAW,aAAa,KAAK,CAAC;AAAA,EAC5E,iBAAiB,OAAO,WACrB,MAAM,OAAO,2BAA2B,GAAG,gBAAgB,aAAa,KAAK,CAAC;AACnF;AAEO,MAAM,yBAA0C;AAIhD,MAAM,sBAAsB,OAA0B;AAAA,EAC3D,SAAS,YAAY;AACnB,UAAM,EAAE,mBAAmB,IAAI,MAAM,OAAO,+CAA+C;AAC3F,WAAO,mBAAmB,EAAE,MAAM,WAAW,QAAQ,IAAI,EAAE,CAAC;AAAA,EAC9D;AAAA,EACA,aAAa,CAAC,aACZ,qBAAqB;AAAA,IACnB,KAAK,SAAS;AAAA,IACd,OAAO,SAAS;AAAA,IAChB,WAAW,SAAS;AAAA,EACtB,CAAC;AACL;AAMO,MAAM,uBACX,CAAC,SACD,OAAO,MAAc,WAAwD;AAC3E,QAAM,MAAM,KAAK,IAAI,IAAI;AACzB,MAAI,WAAW,IAAI,aAAa,UAAU,QAAQ;AAClD,QAAM,UAAU,MAAM,KAAK,QAAQ;AACnC,QAAM,EAAE,UAAU,IAAI,MAAM,OAAO,IAAI;AACvC,UAAQ,eAAe;AACvB,QAAM,SAAS,IAAI,UAAU,KAAK,CAAC,sBAAsB,GAAG,EAAE,QAAQ,CAAC;AACvE,MAAI,MAA2D;AAC/D,MAAI,aAAa;AACjB,SAAO,GAAG,WAAW,CAAC,aAAa;AACjC,UAAM,SAAS;AACf,QAAI,CAAC,WAAY,KAAI,MAAM;AAAA,EAC7B,CAAC;AACD,QAAM,EAAE,SAAS,OAAO,IAAI,0BAA0B,MAAM;AAE5D,QAAM,UAAU,MAAM,OAAO,UAAU;AACvC,UAAQ,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AACzD,MAAI;AACF,UAAM;AAAA,EACR,UAAE;AACA,YAAQ,oBAAoB,SAAS,OAAO;AAAA,EAC9C;AACA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,WAAW;AAAA,MACT,KAAK,MAAM;AACT,qBAAa;AACb,aAAK,IAAI;AAAA,MACX;AAAA,MACA,OAAO,MAAM;AACX,qBAAa;AACb,aAAK,MAAM;AAAA,MACb;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

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

@@ -1,9 +1,11 @@
 import type { JsonValue } from '@finalai/agent-protocol';
+import type { UnmetRequirementIface } from '@finalai/agent-protocol/agent-platform';
 export declare enum AgentClientErrorName {
     Client = "ClientError",
     Decision = "DecisionError",
     TurnRejected = "TurnRejectedError",
-    RealtimeSubscription = "RealtimeSubscriptionError"
+    RealtimeSubscription = "RealtimeSubscriptionError",
+    RequirementsUnmet = "RequirementsUnmetError"
 }
 export declare enum DecisionErrorReason {
     NotFound = "not_found",
@@ -49,7 +51,19 @@ export interface RealtimeSubscriptionErrorIface extends Error, ErrorFieldsIface
     name: AgentClientErrorName.RealtimeSubscription;
     topic: string;
 }
-export type AgentClientError = ClientErrorIface | DecisionErrorIface | TurnRejectedErrorIface | RealtimeSubscriptionErrorIface;
+/**
+ * Something an agent requires was not provided or does not suit it, so nothing
+ * was created. `code` is `requirements_unmet`, or `harness_unsuitable` when only
+ * the harness settings were refused. `status` is 0 when the SDK found it before
+ * sending.
+ */
+export interface RequirementsUnmetErrorIface extends Error, ErrorFieldsIface {
+    name: AgentClientErrorName.RequirementsUnmet;
+    /** The agent's hash or id, when known. */
+    agent: string | null;
+    requirements: UnmetRequirementIface[];
+}
+export type AgentClientError = ClientErrorIface | DecisionErrorIface | TurnRejectedErrorIface | RealtimeSubscriptionErrorIface | RequirementsUnmetErrorIface;
 export interface ClientErrorArgsIface {
     message: string;
     status: number;
@@ -66,6 +80,11 @@ export declare const turnRejectedError: (args: ClientErrorArgsIface & {
     sessionId: string | null;
     state: string | null;
 }) => TurnRejectedErrorIface;
+export declare const requirementsUnmetError: (args: Omit<ClientErrorArgsIface, "message"> & {
+    message?: string;
+    agent: string | null;
+    requirements: UnmetRequirementIface[];
+}) => RequirementsUnmetErrorIface;
 export declare const realtimeSubscriptionError: (args: {
     topic: string;
     code: string;
@@ -80,6 +99,7 @@ export declare const isTerminalRealtimeError: (frame: {
 export declare const isClientError: (cause: unknown) => cause is AgentClientError;
 export declare const isDecisionError: (cause: unknown) => cause is DecisionErrorIface;
 export declare const isTurnRejectedError: (cause: unknown) => cause is TurnRejectedErrorIface;
+export declare const isRequirementsUnmetError: (cause: unknown) => cause is RequirementsUnmetErrorIface;
 export declare const isRealtimeSubscriptionError: (cause: unknown) => cause is RealtimeSubscriptionErrorIface;
 export declare const isRetryableClientError: (cause: unknown) => boolean;
 export {};

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

@@ -4,6 +4,7 @@ var AgentClientErrorName = /* @__PURE__ */ ((AgentClientErrorName2) => {
   AgentClientErrorName2["Decision"] = "DecisionError";
   AgentClientErrorName2["TurnRejected"] = "TurnRejectedError";
   AgentClientErrorName2["RealtimeSubscription"] = "RealtimeSubscriptionError";
+  AgentClientErrorName2["RequirementsUnmet"] = "RequirementsUnmetError";
   return AgentClientErrorName2;
 })(AgentClientErrorName || {});
 var DecisionErrorReason = /* @__PURE__ */ ((DecisionErrorReason2) => {
@@ -47,6 +48,21 @@ const turnRejectedError = (args) => Object.assign(baseError(args), {
   sessionId: args.sessionId,
   state: args.state
 });
+const requirementLine = (requirement) => `${requirement.kind} ${requirement.name} (${requirement.problem}${requirement.detail == null ? "" : `: ${requirement.detail}`})`;
+const requirementsUnmetError = (args) => Object.assign(
+  baseError({
+    ...args,
+    message: args.message ?? `The agent's requirements are not met: ${args.requirements.map(requirementLine).join("; ")}`
+  }),
+  {
+    name: "RequirementsUnmetError" /* RequirementsUnmet */,
+    status: args.status,
+    code: args.code,
+    body: args.body ?? null,
+    agent: args.agent,
+    requirements: args.requirements
+  }
+);
 const realtimeStatusByCode = /* @__PURE__ */ new Map([
   ["unauthorized", 401],
   ["forbidden", 403],
@@ -74,6 +90,7 @@ const errorNameOf = (cause) => {
 const isClientError = (cause) => errorNameOf(cause) != null;
 const isDecisionError = (cause) => errorNameOf(cause) === "DecisionError" /* Decision */;
 const isTurnRejectedError = (cause) => errorNameOf(cause) === "TurnRejectedError" /* TurnRejected */;
+const isRequirementsUnmetError = (cause) => errorNameOf(cause) === "RequirementsUnmetError" /* RequirementsUnmet */;
 const isRealtimeSubscriptionError = (cause) => errorNameOf(cause) === "RealtimeSubscriptionError" /* RealtimeSubscription */;
 const isRetryableClientError = (cause) => isClientError(cause) && (cause.code === "network_error" /* Network */ || cause.status === 429 || cause.status >= 500);
 export {
@@ -85,10 +102,12 @@ export {
   isClientError,
   isDecisionError,
   isRealtimeSubscriptionError,
+  isRequirementsUnmetError,
   isRetryableClientError,
   isTerminalRealtimeError,
   isTurnRejectedError,
   realtimeSubscriptionError,
+  requirementsUnmetError,
   turnRejectedError
 };
 //# sourceMappingURL=errors.mjs.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/agent-client/errors.ts"],
-  "sourcesContent": ["import type { JsonValue } from '@finalai/agent-protocol';\nimport * as z from 'zod';\n\n// Errors are plain `Error` objects with a discriminating `name` (no classes):\n// narrow with the `is*Error` guards, never `instanceof`.\n\nexport enum AgentClientErrorName {\n  Client = 'ClientError',\n  Decision = 'DecisionError',\n  TurnRejected = 'TurnRejectedError',\n  RealtimeSubscription = 'RealtimeSubscriptionError',\n}\n\nexport enum DecisionErrorReason {\n  NotFound = 'not_found',\n  NotInAudience = 'not_in_audience',\n  AlreadyResolved = 'already_resolved',\n  Expired = 'expired',\n}\n\n/** Codes the SDK itself assigns when no HTTP error body applies. */\nexport enum ClientErrorCode {\n  Network = 'network_error',\n  InvalidRequest = 'invalid_request',\n  InvalidResponse = 'invalid_response',\n  UploadFailed = 'upload_failed',\n  NotFound = 'not_found',\n  Closed = 'client_closed',\n  /** The runtime's fetch cannot stream a response body (Streamable HTTP). */\n  StreamUnsupported = 'stream_unsupported',\n  Unknown = 'unknown',\n}\n\ninterface ErrorFieldsIface {\n  /** HTTP status; 0 when no response arrived or the SDK rejected the call locally. */\n  status: number;\n  code: string;\n  body: JsonValue | null;\n}\n\nexport interface ClientErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.Client;\n}\n\n/** Answering a decision outside your audience, already resolved, expired, or unknown. */\nexport interface DecisionErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.Decision;\n  decisionId: string | null;\n  reason: DecisionErrorReason;\n}\n\n/** The session is not accepting prompts; `state` is its ACP/session state. */\nexport interface TurnRejectedErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.TurnRejected;\n  sessionId: string | null;\n  state: string | null;\n}\n\n/** The realtime gateway refused a topic for good (no access, unknown topic, subscription limit). */\nexport interface RealtimeSubscriptionErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.RealtimeSubscription;\n  topic: string;\n}\n\nexport type AgentClientError =\n  | ClientErrorIface\n  | DecisionErrorIface\n  | TurnRejectedErrorIface\n  | RealtimeSubscriptionErrorIface;\n\ntype ErrorBaseKey = 'message' | 'stack' | 'cause';\n\nexport interface ClientErrorArgsIface {\n  message: string;\n  status: number;\n  code: string;\n  body?: JsonValue | null;\n  cause?: unknown;\n}\n\nconst baseError = (args: ClientErrorArgsIface): Error =>\n  args.cause === undefined\n    ? new Error(args.message)\n    : new Error(args.message, { cause: args.cause });\n\nexport const clientError = (args: ClientErrorArgsIface): ClientErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.Client,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n  } satisfies Omit<ClientErrorIface, ErrorBaseKey>);\n\nexport const decisionError = (\n  args: ClientErrorArgsIface & { decisionId: string | null; reason: DecisionErrorReason },\n): DecisionErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.Decision,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n    decisionId: args.decisionId,\n    reason: args.reason,\n  } satisfies Omit<DecisionErrorIface, ErrorBaseKey>);\n\nexport const turnRejectedError = (\n  args: ClientErrorArgsIface & { sessionId: string | null; state: string | null },\n): TurnRejectedErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.TurnRejected,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n    sessionId: args.sessionId,\n    state: args.state,\n  } satisfies Omit<TurnRejectedErrorIface, ErrorBaseKey>);\n\n// Gateway codes map onto the HTTP statuses callers already branch on.\nconst realtimeStatusByCode = new Map<string, number>([\n  ['unauthorized', 401],\n  ['forbidden', 403],\n  ['not_found', 404],\n  ['too_many_subscriptions', 429],\n]);\n\nexport const realtimeSubscriptionError = (args: {\n  topic: string;\n  code: string;\n  message: string;\n}): RealtimeSubscriptionErrorIface =>\n  Object.assign(new Error(args.message), {\n    name: AgentClientErrorName.RealtimeSubscription,\n    status: realtimeStatusByCode.get(args.code) ?? 0,\n    code: args.code,\n    body: null,\n    topic: args.topic,\n  } satisfies Omit<RealtimeSubscriptionErrorIface, ErrorBaseKey>);\n\n/** Whether a realtime error frame ends the subscription: explicit, or by a known terminal code. */\nexport const isTerminalRealtimeError = (frame: {\n  code: string | null;\n  retryable: boolean | null;\n}): boolean =>\n  frame.retryable === false ||\n  (frame.retryable == null && realtimeStatusByCode.has(frame.code ?? ''));\n\nconst errorIdentitySchema = z.object({\n  name: z.nativeEnum(AgentClientErrorName),\n  status: z.number(),\n  code: z.string(),\n  message: z.string(),\n});\n\nconst errorNameOf = (cause: unknown): AgentClientErrorName | null => {\n  const parsed = errorIdentitySchema.safeParse(cause);\n  return parsed.success ? parsed.data.name : null;\n};\n\n/** True for every SDK error (ClientError, DecisionError, TurnRejectedError). */\nexport const isClientError = (cause: unknown): cause is AgentClientError =>\n  errorNameOf(cause) != null;\n\nexport const isDecisionError = (cause: unknown): cause is DecisionErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.Decision;\n\nexport const isTurnRejectedError = (cause: unknown): cause is TurnRejectedErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.TurnRejected;\n\nexport const isRealtimeSubscriptionError = (\n  cause: unknown,\n): cause is RealtimeSubscriptionErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.RealtimeSubscription;\n\nexport const isRetryableClientError = (cause: unknown): boolean =>\n  isClientError(cause) &&\n  (cause.code === ClientErrorCode.Network || cause.status === 429 || cause.status >= 500);\n"],
-  "mappings": "AACA,YAAY,OAAO;AAKZ,IAAK,uBAAL,kBAAKA,0BAAL;AACL,EAAAA,sBAAA,YAAS;AACT,EAAAA,sBAAA,cAAW;AACX,EAAAA,sBAAA,kBAAe;AACf,EAAAA,sBAAA,0BAAuB;AAJb,SAAAA;AAAA,GAAA;AAOL,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,cAAW;AACX,EAAAA,qBAAA,mBAAgB;AAChB,EAAAA,qBAAA,qBAAkB;AAClB,EAAAA,qBAAA,aAAU;AAJA,SAAAA;AAAA,GAAA;AAQL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,aAAU;AACV,EAAAA,iBAAA,oBAAiB;AACjB,EAAAA,iBAAA,qBAAkB;AAClB,EAAAA,iBAAA,kBAAe;AACf,EAAAA,iBAAA,cAAW;AACX,EAAAA,iBAAA,YAAS;AAET,EAAAA,iBAAA,uBAAoB;AACpB,EAAAA,iBAAA,aAAU;AATA,SAAAA;AAAA,GAAA;AA2DZ,MAAM,YAAY,CAAC,SACjB,KAAK,UAAU,SACX,IAAI,MAAM,KAAK,OAAO,IACtB,IAAI,MAAM,KAAK,SAAS,EAAE,OAAO,KAAK,MAAM,CAAC;AAE5C,MAAM,cAAc,CAAC,SAC1B,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AACrB,CAAgD;AAE3C,MAAM,gBAAgB,CAC3B,SAEA,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AAAA,EACnB,YAAY,KAAK;AAAA,EACjB,QAAQ,KAAK;AACf,CAAkD;AAE7C,MAAM,oBAAoB,CAC/B,SAEA,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AAAA,EACnB,WAAW,KAAK;AAAA,EAChB,OAAO,KAAK;AACd,CAAsD;AAGxD,MAAM,uBAAuB,oBAAI,IAAoB;AAAA,EACnD,CAAC,gBAAgB,GAAG;AAAA,EACpB,CAAC,aAAa,GAAG;AAAA,EACjB,CAAC,aAAa,GAAG;AAAA,EACjB,CAAC,0BAA0B,GAAG;AAChC,CAAC;AAEM,MAAM,4BAA4B,CAAC,SAKxC,OAAO,OAAO,IAAI,MAAM,KAAK,OAAO,GAAG;AAAA,EACrC,MAAM;AAAA,EACN,QAAQ,qBAAqB,IAAI,KAAK,IAAI,KAAK;AAAA,EAC/C,MAAM,KAAK;AAAA,EACX,MAAM;AAAA,EACN,OAAO,KAAK;AACd,CAA8D;AAGzD,MAAM,0BAA0B,CAAC,UAItC,MAAM,cAAc,SACnB,MAAM,aAAa,QAAQ,qBAAqB,IAAI,MAAM,QAAQ,EAAE;AAEvE,MAAM,sBAAsB,EAAE,OAAO;AAAA,EACnC,MAAM,EAAE,WAAW,oBAAoB;AAAA,EACvC,QAAQ,EAAE,OAAO;AAAA,EACjB,MAAM,EAAE,OAAO;AAAA,EACf,SAAS,EAAE,OAAO;AACpB,CAAC;AAED,MAAM,cAAc,CAAC,UAAgD;AACnE,QAAM,SAAS,oBAAoB,UAAU,KAAK;AAClD,SAAO,OAAO,UAAU,OAAO,KAAK,OAAO;AAC7C;AAGO,MAAM,gBAAgB,CAAC,UAC5B,YAAY,KAAK,KAAK;AAEjB,MAAM,kBAAkB,CAAC,UAC9B,YAAY,KAAK,MAAM;AAElB,MAAM,sBAAsB,CAAC,UAClC,YAAY,KAAK,MAAM;AAElB,MAAM,8BAA8B,CACzC,UAEA,YAAY,KAAK,MAAM;AAElB,MAAM,yBAAyB,CAAC,UACrC,cAAc,KAAK,MAClB,MAAM,SAAS,iCAA2B,MAAM,WAAW,OAAO,MAAM,UAAU;",
+  "sourcesContent": ["import type { JsonValue } from '@finalai/agent-protocol';\nimport type { UnmetRequirementIface } from '@finalai/agent-protocol/agent-platform';\nimport * as z from 'zod';\n\n// Errors are plain `Error` objects with a discriminating `name` (no classes):\n// narrow with the `is*Error` guards, never `instanceof`.\n\nexport enum AgentClientErrorName {\n  Client = 'ClientError',\n  Decision = 'DecisionError',\n  TurnRejected = 'TurnRejectedError',\n  RealtimeSubscription = 'RealtimeSubscriptionError',\n  RequirementsUnmet = 'RequirementsUnmetError',\n}\n\nexport enum DecisionErrorReason {\n  NotFound = 'not_found',\n  NotInAudience = 'not_in_audience',\n  AlreadyResolved = 'already_resolved',\n  Expired = 'expired',\n}\n\n/** Codes the SDK itself assigns when no HTTP error body applies. */\nexport enum ClientErrorCode {\n  Network = 'network_error',\n  InvalidRequest = 'invalid_request',\n  InvalidResponse = 'invalid_response',\n  UploadFailed = 'upload_failed',\n  NotFound = 'not_found',\n  Closed = 'client_closed',\n  /** The runtime's fetch cannot stream a response body (Streamable HTTP). */\n  StreamUnsupported = 'stream_unsupported',\n  Unknown = 'unknown',\n}\n\ninterface ErrorFieldsIface {\n  /** HTTP status; 0 when no response arrived or the SDK rejected the call locally. */\n  status: number;\n  code: string;\n  body: JsonValue | null;\n}\n\nexport interface ClientErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.Client;\n}\n\n/** Answering a decision outside your audience, already resolved, expired, or unknown. */\nexport interface DecisionErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.Decision;\n  decisionId: string | null;\n  reason: DecisionErrorReason;\n}\n\n/** The session is not accepting prompts; `state` is its ACP/session state. */\nexport interface TurnRejectedErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.TurnRejected;\n  sessionId: string | null;\n  state: string | null;\n}\n\n/** The realtime gateway refused a topic for good (no access, unknown topic, subscription limit). */\nexport interface RealtimeSubscriptionErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.RealtimeSubscription;\n  topic: string;\n}\n\n/**\n * Something an agent requires was not provided or does not suit it, so nothing\n * was created. `code` is `requirements_unmet`, or `harness_unsuitable` when only\n * the harness settings were refused. `status` is 0 when the SDK found it before\n * sending.\n */\nexport interface RequirementsUnmetErrorIface extends Error, ErrorFieldsIface {\n  name: AgentClientErrorName.RequirementsUnmet;\n  /** The agent's hash or id, when known. */\n  agent: string | null;\n  requirements: UnmetRequirementIface[];\n}\n\nexport type AgentClientError =\n  | ClientErrorIface\n  | DecisionErrorIface\n  | TurnRejectedErrorIface\n  | RealtimeSubscriptionErrorIface\n  | RequirementsUnmetErrorIface;\n\ntype ErrorBaseKey = 'message' | 'stack' | 'cause';\n\nexport interface ClientErrorArgsIface {\n  message: string;\n  status: number;\n  code: string;\n  body?: JsonValue | null;\n  cause?: unknown;\n}\n\nconst baseError = (args: ClientErrorArgsIface): Error =>\n  args.cause === undefined\n    ? new Error(args.message)\n    : new Error(args.message, { cause: args.cause });\n\nexport const clientError = (args: ClientErrorArgsIface): ClientErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.Client,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n  } satisfies Omit<ClientErrorIface, ErrorBaseKey>);\n\nexport const decisionError = (\n  args: ClientErrorArgsIface & { decisionId: string | null; reason: DecisionErrorReason },\n): DecisionErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.Decision,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n    decisionId: args.decisionId,\n    reason: args.reason,\n  } satisfies Omit<DecisionErrorIface, ErrorBaseKey>);\n\nexport const turnRejectedError = (\n  args: ClientErrorArgsIface & { sessionId: string | null; state: string | null },\n): TurnRejectedErrorIface =>\n  Object.assign(baseError(args), {\n    name: AgentClientErrorName.TurnRejected,\n    status: args.status,\n    code: args.code,\n    body: args.body ?? null,\n    sessionId: args.sessionId,\n    state: args.state,\n  } satisfies Omit<TurnRejectedErrorIface, ErrorBaseKey>);\n\nconst requirementLine = (requirement: UnmetRequirementIface): string =>\n  `${requirement.kind} ${requirement.name} (${requirement.problem}${\n    requirement.detail == null ? '' : `: ${requirement.detail}`\n  })`;\n\nexport const requirementsUnmetError = (\n  args: Omit<ClientErrorArgsIface, 'message'> & {\n    message?: string;\n    agent: string | null;\n    requirements: UnmetRequirementIface[];\n  },\n): RequirementsUnmetErrorIface =>\n  Object.assign(\n    baseError({\n      ...args,\n      message:\n        args.message ??\n        `The agent's requirements are not met: ${args.requirements.map(requirementLine).join('; ')}`,\n    }),\n    {\n      name: AgentClientErrorName.RequirementsUnmet,\n      status: args.status,\n      code: args.code,\n      body: args.body ?? null,\n      agent: args.agent,\n      requirements: args.requirements,\n    } satisfies Omit<RequirementsUnmetErrorIface, ErrorBaseKey>,\n  );\n\n// Gateway codes map onto the HTTP statuses callers already branch on.\nconst realtimeStatusByCode = new Map<string, number>([\n  ['unauthorized', 401],\n  ['forbidden', 403],\n  ['not_found', 404],\n  ['too_many_subscriptions', 429],\n]);\n\nexport const realtimeSubscriptionError = (args: {\n  topic: string;\n  code: string;\n  message: string;\n}): RealtimeSubscriptionErrorIface =>\n  Object.assign(new Error(args.message), {\n    name: AgentClientErrorName.RealtimeSubscription,\n    status: realtimeStatusByCode.get(args.code) ?? 0,\n    code: args.code,\n    body: null,\n    topic: args.topic,\n  } satisfies Omit<RealtimeSubscriptionErrorIface, ErrorBaseKey>);\n\n/** Whether a realtime error frame ends the subscription: explicit, or by a known terminal code. */\nexport const isTerminalRealtimeError = (frame: {\n  code: string | null;\n  retryable: boolean | null;\n}): boolean =>\n  frame.retryable === false ||\n  (frame.retryable == null && realtimeStatusByCode.has(frame.code ?? ''));\n\nconst errorIdentitySchema = z.object({\n  name: z.nativeEnum(AgentClientErrorName),\n  status: z.number(),\n  code: z.string(),\n  message: z.string(),\n});\n\nconst errorNameOf = (cause: unknown): AgentClientErrorName | null => {\n  const parsed = errorIdentitySchema.safeParse(cause);\n  return parsed.success ? parsed.data.name : null;\n};\n\n/** True for every SDK error (ClientError, DecisionError, TurnRejectedError). */\nexport const isClientError = (cause: unknown): cause is AgentClientError =>\n  errorNameOf(cause) != null;\n\nexport const isDecisionError = (cause: unknown): cause is DecisionErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.Decision;\n\nexport const isTurnRejectedError = (cause: unknown): cause is TurnRejectedErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.TurnRejected;\n\nexport const isRequirementsUnmetError = (cause: unknown): cause is RequirementsUnmetErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.RequirementsUnmet;\n\nexport const isRealtimeSubscriptionError = (\n  cause: unknown,\n): cause is RealtimeSubscriptionErrorIface =>\n  errorNameOf(cause) === AgentClientErrorName.RealtimeSubscription;\n\nexport const isRetryableClientError = (cause: unknown): boolean =>\n  isClientError(cause) &&\n  (cause.code === ClientErrorCode.Network || cause.status === 429 || cause.status >= 500);\n"],
+  "mappings": "AAEA,YAAY,OAAO;AAKZ,IAAK,uBAAL,kBAAKA,0BAAL;AACL,EAAAA,sBAAA,YAAS;AACT,EAAAA,sBAAA,cAAW;AACX,EAAAA,sBAAA,kBAAe;AACf,EAAAA,sBAAA,0BAAuB;AACvB,EAAAA,sBAAA,uBAAoB;AALV,SAAAA;AAAA,GAAA;AAQL,IAAK,sBAAL,kBAAKC,yBAAL;AACL,EAAAA,qBAAA,cAAW;AACX,EAAAA,qBAAA,mBAAgB;AAChB,EAAAA,qBAAA,qBAAkB;AAClB,EAAAA,qBAAA,aAAU;AAJA,SAAAA;AAAA,GAAA;AAQL,IAAK,kBAAL,kBAAKC,qBAAL;AACL,EAAAA,iBAAA,aAAU;AACV,EAAAA,iBAAA,oBAAiB;AACjB,EAAAA,iBAAA,qBAAkB;AAClB,EAAAA,iBAAA,kBAAe;AACf,EAAAA,iBAAA,cAAW;AACX,EAAAA,iBAAA,YAAS;AAET,EAAAA,iBAAA,uBAAoB;AACpB,EAAAA,iBAAA,aAAU;AATA,SAAAA;AAAA,GAAA;AAyEZ,MAAM,YAAY,CAAC,SACjB,KAAK,UAAU,SACX,IAAI,MAAM,KAAK,OAAO,IACtB,IAAI,MAAM,KAAK,SAAS,EAAE,OAAO,KAAK,MAAM,CAAC;AAE5C,MAAM,cAAc,CAAC,SAC1B,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AACrB,CAAgD;AAE3C,MAAM,gBAAgB,CAC3B,SAEA,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AAAA,EACnB,YAAY,KAAK;AAAA,EACjB,QAAQ,KAAK;AACf,CAAkD;AAE7C,MAAM,oBAAoB,CAC/B,SAEA,OAAO,OAAO,UAAU,IAAI,GAAG;AAAA,EAC7B,MAAM;AAAA,EACN,QAAQ,KAAK;AAAA,EACb,MAAM,KAAK;AAAA,EACX,MAAM,KAAK,QAAQ;AAAA,EACnB,WAAW,KAAK;AAAA,EAChB,OAAO,KAAK;AACd,CAAsD;AAExD,MAAM,kBAAkB,CAAC,gBACvB,GAAG,YAAY,IAAI,IAAI,YAAY,IAAI,KAAK,YAAY,OAAO,GAC7D,YAAY,UAAU,OAAO,KAAK,KAAK,YAAY,MAAM,EAC3D;AAEK,MAAM,yBAAyB,CACpC,SAMA,OAAO;AAAA,EACL,UAAU;AAAA,IACR,GAAG;AAAA,IACH,SACE,KAAK,WACL,yCAAyC,KAAK,aAAa,IAAI,eAAe,EAAE,KAAK,IAAI,CAAC;AAAA,EAC9F,CAAC;AAAA,EACD;AAAA,IACE,MAAM;AAAA,IACN,QAAQ,KAAK;AAAA,IACb,MAAM,KAAK;AAAA,IACX,MAAM,KAAK,QAAQ;AAAA,IACnB,OAAO,KAAK;AAAA,IACZ,cAAc,KAAK;AAAA,EACrB;AACF;AAGF,MAAM,uBAAuB,oBAAI,IAAoB;AAAA,EACnD,CAAC,gBAAgB,GAAG;AAAA,EACpB,CAAC,aAAa,GAAG;AAAA,EACjB,CAAC,aAAa,GAAG;AAAA,EACjB,CAAC,0BAA0B,GAAG;AAChC,CAAC;AAEM,MAAM,4BAA4B,CAAC,SAKxC,OAAO,OAAO,IAAI,MAAM,KAAK,OAAO,GAAG;AAAA,EACrC,MAAM;AAAA,EACN,QAAQ,qBAAqB,IAAI,KAAK,IAAI,KAAK;AAAA,EAC/C,MAAM,KAAK;AAAA,EACX,MAAM;AAAA,EACN,OAAO,KAAK;AACd,CAA8D;AAGzD,MAAM,0BAA0B,CAAC,UAItC,MAAM,cAAc,SACnB,MAAM,aAAa,QAAQ,qBAAqB,IAAI,MAAM,QAAQ,EAAE;AAEvE,MAAM,sBAAsB,EAAE,OAAO;AAAA,EACnC,MAAM,EAAE,WAAW,oBAAoB;AAAA,EACvC,QAAQ,EAAE,OAAO;AAAA,EACjB,MAAM,EAAE,OAAO;AAAA,EACf,SAAS,EAAE,OAAO;AACpB,CAAC;AAED,MAAM,cAAc,CAAC,UAAgD;AACnE,QAAM,SAAS,oBAAoB,UAAU,KAAK;AAClD,SAAO,OAAO,UAAU,OAAO,KAAK,OAAO;AAC7C;AAGO,MAAM,gBAAgB,CAAC,UAC5B,YAAY,KAAK,KAAK;AAEjB,MAAM,kBAAkB,CAAC,UAC9B,YAAY,KAAK,MAAM;AAElB,MAAM,sBAAsB,CAAC,UAClC,YAAY,KAAK,MAAM;AAElB,MAAM,2BAA2B,CAAC,UACvC,YAAY,KAAK,MAAM;AAElB,MAAM,8BAA8B,CACzC,UAEA,YAAY,KAAK,MAAM;AAElB,MAAM,yBAAyB,CAAC,UACrC,cAAc,KAAK,MAClB,MAAM,SAAS,iCAA2B,MAAM,WAAW,OAAO,MAAM,UAAU;",
   "names": ["AgentClientErrorName", "DecisionErrorReason", "ClientErrorCode"]
 }

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

@@ -0,0 +1,62 @@
+import { type CreateEventSubscriptionRequestIface, type CreateEventSubscriptionResponseIface, type EventsPageIface, type EventSubscriptionIface, type PlatformEventKind, type PlatformEventType, type UpdateEventSubscriptionRequestIface } from '@finalai/agent-protocol/agent-platform';
+import { type ClientContextIface, type EnumInput, type SignalOptionsIface } from "./context.mjs";
+/** How long `stream()` waits before reading again once it has caught up. */
+export declare const EVENTS_POLL_INTERVAL_MS = 5000;
+export interface ListEventsOptionsIface extends SignalOptionsIface {
+    /** A previous page's or delivery's `cursor`; omitted, the feed's head. */
+    after?: string;
+    kinds?: readonly EnumInput<PlatformEventKind>[];
+    limit?: number;
+}
+export interface StreamEventsOptionsIface extends Omit<ListEventsOptionsIface, 'limit'> {
+    /** Defaults to `EVENTS_POLL_INTERVAL_MS`. */
+    pollIntervalMs?: number;
+}
+export interface EventsApiIface {
+    /**
+     * One page of events after `after`, oldest first. An expired cursor (older
+     * than the feed keeps) fails with `cursor_expired` (410).
+     */
+    list: (options?: ListEventsOptionsIface) => Promise<EventsPageIface>;
+    /**
+     * Every event after `after`, polling the feed once caught up, until
+     * `signal` aborts or the client closes. A delivery may repeat an event:
+     * deduplicate by `id`.
+     */
+    stream: (options?: StreamEventsOptionsIface) => AsyncIterableIterator<PlatformEventType>;
+}
+export interface EventSubscriptionsApiIface {
+    /**
+     * Pushes events to `url`, signed with the returned `signingSecret` (shown
+     * only here; verify deliveries with `verifyWebhook` from
+     * `@finalai/agents/webhooks`). Delivery starts at the feed's head unless
+     * `after` names a cursor.
+     */
+    create: (args: CreateEventSubscriptionRequestIface & SignalOptionsIface) => Promise<CreateEventSubscriptionResponseIface>;
+    list: (options?: SignalOptionsIface) => Promise<EventSubscriptionIface[]>;
+    get: (args: {
+        id: string;
+    } & SignalOptionsIface) => Promise<EventSubscriptionIface>;
+    /** `state: 'active'` re-enables a disabled subscription and resets its retries. */
+    update: (args: {
+        id: string;
+    } & UpdateEventSubscriptionRequestIface & SignalOptionsIface) => Promise<EventSubscriptionIface>;
+    delete: (args: {
+        id: string;
+    } & SignalOptionsIface) => Promise<void>;
+    /** Delivers again from `after`, within the feed's retention. */
+    replay: (args: {
+        id: string;
+        after: string;
+    } & SignalOptionsIface) => Promise<EventSubscriptionIface>;
+}
+export declare const createEventsApi: (args: {
+    context: ClientContextIface;
+    /** Narrows to this project and those below it; null for everything the caller can see. */
+    projectId: string | null;
+}) => EventsApiIface;
+export declare const createEventSubscriptionsApi: (args: {
+    context: ClientContextIface;
+    /** `/v1/projects/:projectId/event-subscriptions`, or `/v1/apps/me/event-subscriptions`. */
+    basePath: string;
+}) => EventSubscriptionsApiIface;

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

@@ -0,0 +1,107 @@
+import {
+  createEventSubscriptionRequestSchema,
+  createEventSubscriptionResponseSchema,
+  eventsPageSchema,
+  eventSubscriptionListSchema,
+  eventSubscriptionResponseSchema,
+  okResponseSchema,
+  replayEventSubscriptionRequestSchema,
+  updateEventSubscriptionRequestSchema
+} from "@finalai/agent-protocol/agent-platform";
+import {
+  encodePath
+} from "./context.mjs";
+import { HttpMethod } from "./http.mjs";
+const EVENTS_POLL_INTERVAL_MS = 5e3;
+const sleepUnlessAborted = (sleep, signal) => new Promise((resolve, reject) => {
+  if (signal.aborted) {
+    reject(signal.reason);
+    return;
+  }
+  const onAbort = () => reject(signal.reason);
+  signal.addEventListener("abort", onAbort, { once: true });
+  sleep.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+});
+const createEventsApi = (args) => {
+  const { context } = args;
+  const list = (options) => context.http.request({
+    method: HttpMethod.Get,
+    path: "/v1/events",
+    query: {
+      after: options?.after,
+      limit: options?.limit,
+      kinds: options?.kinds == null ? void 0 : options.kinds.join(","),
+      projectId: args.projectId ?? void 0
+    },
+    response: eventsPageSchema,
+    signal: options?.signal
+  });
+  const stream = async function* (options) {
+    const signal = options?.signal == null ? context.closeSignal : AbortSignal.any([context.closeSignal, options.signal]);
+    let after = options?.after;
+    for (; ; ) {
+      const page = await list({ after, kinds: options?.kinds, signal });
+      yield* page.events;
+      after = page.cursor ?? after;
+      if (page.hasMore && page.events.length > 0) continue;
+      await sleepUnlessAborted(
+        context.timing.sleep(options?.pollIntervalMs ?? EVENTS_POLL_INTERVAL_MS),
+        signal
+      );
+    }
+  };
+  return { list, stream };
+};
+const createEventSubscriptionsApi = (args) => {
+  const { http } = args.context;
+  const path = (id, suffix = "") => id == null ? args.basePath : `${args.basePath}/${encodePath(id)}${suffix}`;
+  return {
+    create: ({ signal, ...value }) => http.request({
+      method: HttpMethod.Post,
+      path: path(),
+      body: { schema: createEventSubscriptionRequestSchema, value },
+      response: createEventSubscriptionResponseSchema,
+      signal
+    }),
+    list: async (options) => (await http.request({
+      method: HttpMethod.Get,
+      path: path(),
+      response: eventSubscriptionListSchema,
+      signal: options?.signal
+    })).subscriptions,
+    get: async ({ id, signal }) => (await http.request({
+      method: HttpMethod.Get,
+      path: path(id),
+      response: eventSubscriptionResponseSchema,
+      signal
+    })).subscription,
+    update: async ({ id, signal, ...value }) => (await http.request({
+      method: HttpMethod.Patch,
+      path: path(id),
+      body: { schema: updateEventSubscriptionRequestSchema, value },
+      response: eventSubscriptionResponseSchema,
+      signal
+    })).subscription,
+    delete: async ({ id, signal }) => {
+      await http.request({
+        method: HttpMethod.Delete,
+        path: path(id),
+        response: okResponseSchema,
+        signal
+      });
+    },
+    replay: async ({ id, after, signal }) => (await http.request({
+      method: HttpMethod.Post,
+      path: path(id, "/replay"),
+      body: { schema: replayEventSubscriptionRequestSchema, value: { after } },
+      response: eventSubscriptionResponseSchema,
+      signal
+    })).subscription
+  };
+};
+export {
+  EVENTS_POLL_INTERVAL_MS,
+  createEventSubscriptionsApi,
+  createEventsApi
+};
+//# sourceMappingURL=events.mjs.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/events.ts"],
+  "sourcesContent": ["import {\n  createEventSubscriptionRequestSchema,\n  createEventSubscriptionResponseSchema,\n  eventsPageSchema,\n  eventSubscriptionListSchema,\n  eventSubscriptionResponseSchema,\n  okResponseSchema,\n  replayEventSubscriptionRequestSchema,\n  updateEventSubscriptionRequestSchema,\n  type CreateEventSubscriptionRequestIface,\n  type CreateEventSubscriptionResponseIface,\n  type EventsPageIface,\n  type EventSubscriptionIface,\n  type PlatformEventKind,\n  type PlatformEventType,\n  type UpdateEventSubscriptionRequestIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport {\n  encodePath,\n  type ClientContextIface,\n  type EnumInput,\n  type SignalOptionsIface,\n} from \"./context.mjs\";\nimport { HttpMethod } from \"./http.mjs\";\n\n// The event feed (`GET /v1/events`): what changed in the projects the caller\n// can see, in commit order, and event subscriptions that push it to a URL.\n\n/** How long `stream()` waits before reading again once it has caught up. */\nexport const EVENTS_POLL_INTERVAL_MS = 5_000;\n\nexport interface ListEventsOptionsIface extends SignalOptionsIface {\n  /** A previous page's or delivery's `cursor`; omitted, the feed's head. */\n  after?: string;\n  kinds?: readonly EnumInput<PlatformEventKind>[];\n  limit?: number;\n}\n\nexport interface StreamEventsOptionsIface extends Omit<ListEventsOptionsIface, 'limit'> {\n  /** Defaults to `EVENTS_POLL_INTERVAL_MS`. */\n  pollIntervalMs?: number;\n}\n\nexport interface EventsApiIface {\n  /**\n   * One page of events after `after`, oldest first. An expired cursor (older\n   * than the feed keeps) fails with `cursor_expired` (410).\n   */\n  list: (options?: ListEventsOptionsIface) => Promise<EventsPageIface>;\n  /**\n   * Every event after `after`, polling the feed once caught up, until\n   * `signal` aborts or the client closes. A delivery may repeat an event:\n   * deduplicate by `id`.\n   */\n  stream: (options?: StreamEventsOptionsIface) => AsyncIterableIterator<PlatformEventType>;\n}\n\nexport interface EventSubscriptionsApiIface {\n  /**\n   * Pushes events to `url`, signed with the returned `signingSecret` (shown\n   * only here; verify deliveries with `verifyWebhook` from\n   * `@finalai/agents/webhooks`). Delivery starts at the feed's head unless\n   * `after` names a cursor.\n   */\n  create: (\n    args: CreateEventSubscriptionRequestIface & SignalOptionsIface,\n  ) => Promise<CreateEventSubscriptionResponseIface>;\n  list: (options?: SignalOptionsIface) => Promise<EventSubscriptionIface[]>;\n  get: (args: { id: string } & SignalOptionsIface) => Promise<EventSubscriptionIface>;\n  /** `state: 'active'` re-enables a disabled subscription and resets its retries. */\n  update: (\n    args: { id: string } & UpdateEventSubscriptionRequestIface & SignalOptionsIface,\n  ) => Promise<EventSubscriptionIface>;\n  delete: (args: { id: string } & SignalOptionsIface) => Promise<void>;\n  /** Delivers again from `after`, within the feed's retention. */\n  replay: (\n    args: { id: string; after: string } & SignalOptionsIface,\n  ) => Promise<EventSubscriptionIface>;\n}\n\n// Rejects with the signal's reason as soon as it aborts.\nconst sleepUnlessAborted = (sleep: Promise<void>, signal: AbortSignal): Promise<void> =>\n  new Promise((resolve, reject) => {\n    if (signal.aborted) {\n      reject(signal.reason);\n      return;\n    }\n    const onAbort = (): void => reject(signal.reason);\n    signal.addEventListener('abort', onAbort, { once: true });\n    sleep.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));\n  });\n\nexport const createEventsApi = (args: {\n  context: ClientContextIface;\n  /** Narrows to this project and those below it; null for everything the caller can see. */\n  projectId: string | null;\n}): EventsApiIface => {\n  const { context } = args;\n  const list: EventsApiIface['list'] = (options) =>\n    context.http.request({\n      method: HttpMethod.Get,\n      path: '/v1/events',\n      query: {\n        after: options?.after,\n        limit: options?.limit,\n        kinds: options?.kinds == null ? undefined : options.kinds.join(','),\n        projectId: args.projectId ?? undefined,\n      },\n      response: eventsPageSchema,\n      signal: options?.signal,\n    });\n  const stream = async function* (\n    options?: StreamEventsOptionsIface,\n  ): AsyncGenerator<PlatformEventType> {\n    const signal =\n      options?.signal == null\n        ? context.closeSignal\n        : AbortSignal.any([context.closeSignal, options.signal]);\n    let after = options?.after;\n    for (;;) {\n      const page = await list({ after, kinds: options?.kinds, signal });\n      yield* page.events;\n      after = page.cursor ?? after;\n      if (page.hasMore && page.events.length > 0) continue;\n      await sleepUnlessAborted(\n        context.timing.sleep(options?.pollIntervalMs ?? EVENTS_POLL_INTERVAL_MS),\n        signal,\n      );\n    }\n  };\n  return { list, stream };\n};\n\nexport const createEventSubscriptionsApi = (args: {\n  context: ClientContextIface;\n  /** `/v1/projects/:projectId/event-subscriptions`, or `/v1/apps/me/event-subscriptions`. */\n  basePath: string;\n}): EventSubscriptionsApiIface => {\n  const { http } = args.context;\n  const path = (id?: string, suffix = ''): string =>\n    id == null ? args.basePath : `${args.basePath}/${encodePath(id)}${suffix}`;\n  return {\n    create: ({ signal, ...value }) =>\n      http.request({\n        method: HttpMethod.Post,\n        path: path(),\n        body: { schema: createEventSubscriptionRequestSchema, value },\n        response: createEventSubscriptionResponseSchema,\n        signal,\n      }),\n    list: async (options) =>\n      (\n        await http.request({\n          method: HttpMethod.Get,\n          path: path(),\n          response: eventSubscriptionListSchema,\n          signal: options?.signal,\n        })\n      ).subscriptions,\n    get: async ({ id, signal }) =>\n      (\n        await http.request({\n          method: HttpMethod.Get,\n          path: path(id),\n          response: eventSubscriptionResponseSchema,\n          signal,\n        })\n      ).subscription,\n    update: async ({ id, signal, ...value }) =>\n      (\n        await http.request({\n          method: HttpMethod.Patch,\n          path: path(id),\n          body: { schema: updateEventSubscriptionRequestSchema, value },\n          response: eventSubscriptionResponseSchema,\n          signal,\n        })\n      ).subscription,\n    delete: async ({ id, signal }) => {\n      await http.request({\n        method: HttpMethod.Delete,\n        path: path(id),\n        response: okResponseSchema,\n        signal,\n      });\n    },\n    replay: async ({ id, after, signal }) =>\n      (\n        await http.request({\n          method: HttpMethod.Post,\n          path: path(id, '/replay'),\n          body: { schema: replayEventSubscriptionRequestSchema, value: { after } },\n          response: eventSubscriptionResponseSchema,\n          signal,\n        })\n      ).subscription,\n  };\n};\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAQK;AACP;AAAA,EACE;AAAA,OAIK;AACP,SAAS,kBAAkB;AAMpB,MAAM,0BAA0B;AAoDvC,MAAM,qBAAqB,CAAC,OAAsB,WAChD,IAAI,QAAQ,CAAC,SAAS,WAAW;AAC/B,MAAI,OAAO,SAAS;AAClB,WAAO,OAAO,MAAM;AACpB;AAAA,EACF;AACA,QAAM,UAAU,MAAY,OAAO,OAAO,MAAM;AAChD,SAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAK,CAAC;AACxD,QAAM,KAAK,SAAS,MAAM,EAAE,QAAQ,MAAM,OAAO,oBAAoB,SAAS,OAAO,CAAC;AACxF,CAAC;AAEI,MAAM,kBAAkB,CAAC,SAIV;AACpB,QAAM,EAAE,QAAQ,IAAI;AACpB,QAAM,OAA+B,CAAC,YACpC,QAAQ,KAAK,QAAQ;AAAA,IACnB,QAAQ,WAAW;AAAA,IACnB,MAAM;AAAA,IACN,OAAO;AAAA,MACL,OAAO,SAAS;AAAA,MAChB,OAAO,SAAS;AAAA,MAChB,OAAO,SAAS,SAAS,OAAO,SAAY,QAAQ,MAAM,KAAK,GAAG;AAAA,MAClE,WAAW,KAAK,aAAa;AAAA,IAC/B;AAAA,IACA,UAAU;AAAA,IACV,QAAQ,SAAS;AAAA,EACnB,CAAC;AACH,QAAM,SAAS,iBACb,SACmC;AACnC,UAAM,SACJ,SAAS,UAAU,OACf,QAAQ,cACR,YAAY,IAAI,CAAC,QAAQ,aAAa,QAAQ,MAAM,CAAC;AAC3D,QAAI,QAAQ,SAAS;AACrB,eAAS;AACP,YAAM,OAAO,MAAM,KAAK,EAAE,OAAO,OAAO,SAAS,OAAO,OAAO,CAAC;AAChE,aAAO,KAAK;AACZ,cAAQ,KAAK,UAAU;AACvB,UAAI,KAAK,WAAW,KAAK,OAAO,SAAS,EAAG;AAC5C,YAAM;AAAA,QACJ,QAAQ,OAAO,MAAM,SAAS,kBAAkB,uBAAuB;AAAA,QACvE;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,MAAM,OAAO;AACxB;AAEO,MAAM,8BAA8B,CAAC,SAIV;AAChC,QAAM,EAAE,KAAK,IAAI,KAAK;AACtB,QAAM,OAAO,CAAC,IAAa,SAAS,OAClC,MAAM,OAAO,KAAK,WAAW,GAAG,KAAK,QAAQ,IAAI,WAAW,EAAE,CAAC,GAAG,MAAM;AAC1E,SAAO;AAAA,IACL,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,MAC1B,KAAK,QAAQ;AAAA,MACX,QAAQ,WAAW;AAAA,MACnB,MAAM,KAAK;AAAA,MACX,MAAM,EAAE,QAAQ,sCAAsC,MAAM;AAAA,MAC5D,UAAU;AAAA,MACV;AAAA,IACF,CAAC;AAAA,IACH,MAAM,OAAO,aAET,MAAM,KAAK,QAAQ;AAAA,MACjB,QAAQ,WAAW;AAAA,MACnB,MAAM,KAAK;AAAA,MACX,UAAU;AAAA,MACV,QAAQ,SAAS;AAAA,IACnB,CAAC,GACD;AAAA,IACJ,KAAK,OAAO,EAAE,IAAI,OAAO,OAErB,MAAM,KAAK,QAAQ;AAAA,MACjB,QAAQ,WAAW;AAAA,MACnB,MAAM,KAAK,EAAE;AAAA,MACb,UAAU;AAAA,MACV;AAAA,IACF,CAAC,GACD;AAAA,IACJ,QAAQ,OAAO,EAAE,IAAI,QAAQ,GAAG,MAAM,OAElC,MAAM,KAAK,QAAQ;AAAA,MACjB,QAAQ,WAAW;AAAA,MACnB,MAAM,KAAK,EAAE;AAAA,MACb,MAAM,EAAE,QAAQ,sCAAsC,MAAM;AAAA,MAC5D,UAAU;AAAA,MACV;AAAA,IACF,CAAC,GACD;AAAA,IACJ,QAAQ,OAAO,EAAE,IAAI,OAAO,MAAM;AAChC,YAAM,KAAK,QAAQ;AAAA,QACjB,QAAQ,WAAW;AAAA,QACnB,MAAM,KAAK,EAAE;AAAA,QACb,UAAU;AAAA,QACV;AAAA,MACF,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,OAAO,EAAE,IAAI,OAAO,OAAO,OAE/B,MAAM,KAAK,QAAQ;AAAA,MACjB,QAAQ,WAAW;AAAA,MACnB,MAAM,KAAK,IAAI,SAAS;AAAA,MACxB,MAAM,EAAE,QAAQ,sCAAsC,OAAO,EAAE,MAAM,EAAE;AAAA,MACvE,UAAU;AAAA,MACV;AAAA,IACF,CAAC,GACD;AAAA,EACN;AACF;",
+  "names": []
+}

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

@@ -0,0 +1,66 @@
+import { type Capability } from '@finalai/agent-protocol';
+import { type AcpAdapterDefinitionInfoIface, type AcpAdapterDefinitionSummaryIface, type DefinitionPublicationIface, type DefinitionVisibility, type HarnessCheckResponseIface, type HarnessDefinitionInfoIface, type HarnessDefinitionSummaryIface, type HarnessSettingsIface, type SubscriptionAllowanceIface } from '@finalai/agent-protocol/agent-platform';
+import { type AcpAdapterDefinitionInputIface, type HarnessDefinitionInputIface } from '@finalai/agent-provider/harness-definition';
+import type { AgentInput } from "./agent-input.mjs";
+import { type ClientContextIface, type EnumInput, type SignalOptionsIface } from "./context.mjs";
+export type DefinitionSelectorIface = {
+    name: string;
+} | {
+    hash: string;
+};
+export interface SubscriptionAllowancesApiIface {
+    /** The harnesses subscriptions may reach in this project, the catalog's included. */
+    list: (options?: SignalOptionsIface) => Promise<SubscriptionAllowanceIface[]>;
+    /** Lets personal and shared subscriptions reach `harness`. */
+    allow: (args: {
+        harness: string;
+    } & SignalOptionsIface) => Promise<SubscriptionAllowanceIface>;
+    revoke: (args: {
+        harness: string;
+    } & SignalOptionsIface) => Promise<void>;
+}
+export interface HarnessesApiIface {
+    /**
+     * Whether harness settings suit an agent, where the harness would run, and
+     * which of its compute that environment covers. `agent` is the agent or its
+     * content hash; `compute` places a harness that names no environment.
+     */
+    check: (args: {
+        agent: string | AgentInput;
+        harness: HarnessSettingsIface;
+        compute?: Partial<Record<Capability, string>>;
+    } & SignalOptionsIface) => Promise<HarnessCheckResponseIface>;
+    /**
+     * Stores a harness definition and points `name` at it. `visibility: 'public'`
+     * also makes the name public under the project's publisher handle.
+     */
+    publish: (args: {
+        harness: HarnessDefinitionInputIface;
+        name: string;
+        visibility?: EnumInput<DefinitionVisibility>;
+    } & SignalOptionsIface) => Promise<DefinitionPublicationIface>;
+    get: (selector: DefinitionSelectorIface & SignalOptionsIface) => Promise<HarnessDefinitionInfoIface>;
+    /** The harnesses this project can name by bare name: its own and its ancestors'. */
+    list: (options?: SignalOptionsIface) => Promise<HarnessDefinitionSummaryIface[]>;
+    allowances: SubscriptionAllowancesApiIface;
+}
+export interface AcpAdaptersApiIface {
+    /** Stores an ACP adapter definition and points `name` at it; see `harnesses.publish` for `visibility`. */
+    publish: (args: {
+        adapter: AcpAdapterDefinitionInputIface;
+        name: string;
+        visibility?: EnumInput<DefinitionVisibility>;
+    } & SignalOptionsIface) => Promise<DefinitionPublicationIface>;
+    get: (selector: DefinitionSelectorIface & SignalOptionsIface) => Promise<AcpAdapterDefinitionInfoIface>;
+    list: (options?: SignalOptionsIface) => Promise<AcpAdapterDefinitionSummaryIface[]>;
+}
+export declare const createHarnessesApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+    /** Stores an agent's document so the platform can check against it; returns its hash. */
+    store: (agent: AgentInput, signal?: AbortSignal) => Promise<string>;
+}) => HarnessesApiIface;
+export declare const createAcpAdaptersApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+}) => AcpAdaptersApiIface;