@finalai/agents 0.11.0 → 0.13.0

package/dist/modules/cli/output.mjs

@@ -1,94 +1,16 @@
-import {
-  findDynamicSlots,
-  formatProviderRef,
-  isDynamicSlot
-} from "@finalai/agent-provider";
-import * as z from "zod";
-import { isClientError } from "../agent-client/errors.mjs";
-import { diagnosticSchema } from "../agent-client/index.mjs";
-const listOrNone = (items) => items.length === 0 ? "none" : items.join(", ");
-const manifestSummaryLines = (manifest) => {
-  const lines = [`agent: ${manifest.identity.name}`];
-  if (manifest.identity.description != null)
-    lines.push(`description: ${manifest.identity.description}`);
-  lines.push(`harness: ${formatProviderRef(manifest.harness.harness)}`);
-  lines.push(
-    `mcp servers: ${isDynamicSlot(manifest.mcpServers) ? "dynamic" : listOrNone(manifest.mcpServers.map((server) => `${server.key} (${server.kind})`))}`
-  );
-  lines.push(
-    `sandboxes: ${isDynamicSlot(manifest.sandboxes) ? "dynamic" : listOrNone(Object.keys(manifest.sandboxes))}`
-  );
-  lines.push(
-    `base tools: ${listOrNone(
-      Object.entries(manifest.tools.base).map(
-        ([capability, binding]) => `${capability} \u2192 ${binding?.target ?? "?"}`
-      )
-    )}`
-  );
-  lines.push(`channels: ${listOrNone(manifest.channels.map((channel) => channel.key))}`);
-  lines.push(
-    `schedules: ${listOrNone(
-      manifest.schedules.map(
-        (schedule) => `${schedule.key} (${schedule.cron}, ${schedule.timezone})`
-      )
-    )}`
-  );
-  lines.push(`secrets: ${listOrNone(manifest.secrets)}`);
-  lines.push(`dynamic slots: ${listOrNone(findDynamicSlots(manifest).map((slot) => slot.path))}`);
-  lines.push(`bundle: ${manifest.bundle?.hash ?? "none"}`);
-  return lines;
-};
-const hookLines = (manifest) => manifest.hooks.length === 0 ? ["hooks: none"] : [
-  "hooks:",
-  ...manifest.hooks.map(
-    (hook) => `  ${hook.slug} (${hook.export}): ${hook.events.join(", ")}`
-  )
-];
-const reportLines = (report) => [
-  `compatibility with ${formatProviderRef(report.harness)}: ${report.ok ? "ok" : "incompatible"}`,
-  ...report.rows.map((row) => `  ${row.item}: ${row.result} (${row.why})`)
-];
-const diagnosticLine = (item) => `${item.severity}: ${item.path == null ? "" : `${item.path}: `}${item.message} [${item.code}]`;
-const errorDiagnosticsSchema = z.object({
-  error: z.object({
-    details: z.object({ diagnostics: z.array(diagnosticSchema) }).nullable()
-  })
-});
+import { isClientError, isRequirementsUnmetError } from "../agent-client/errors.mjs";
 const errorLines = (cause) => {
   if (!isClientError(cause))
     return [`error: ${cause instanceof Error ? cause.message : String(cause)}`];
   const lines = [`error: ${cause.message}${cause.status === 0 ? "" : ` (HTTP ${cause.status})`}`];
-  const parsed = errorDiagnosticsSchema.safeParse(cause.body);
-  for (const item of parsed.success ? parsed.data.error.details?.diagnostics ?? [] : []) {
-    lines.push(`  ${item.severity}: ${item.file == null ? "" : `${item.file}: `}${item.message}`);
-  }
-  return lines;
-};
-const publishResultLines = (result) => {
-  const revision = result.revision;
-  const lines = [
-    `${result.created ? "published" : "already published"}: revision ${revision.number} (${revision.id})`,
-    `commit: ${revision.commitSha ?? "unknown"}`,
-    `bundle: ${revision.bundleHash ?? "none"}`
-  ];
-  for (const item of result.diagnostics) lines.push(`${item.severity}: ${item.message}`);
-  for (const channel of result.channels) {
-    lines.push(`channel ${channel.key} (${channel.bindingId}):`);
-    for (const route of channel.routes) {
-      lines.push(`  ${route.method} ${route.url ?? route.aliasUrl}`);
-      if (route.url != null) lines.push(`    alias: ${route.aliasUrl}`);
-    }
-    if (channel.webhookSecret != null)
-      lines.push(`  signing secret (shown once): ${channel.webhookSecret}`);
-  }
+  if (isRequirementsUnmetError(cause))
+    for (const item of cause.requirements)
+      lines.push(
+        `  ${item.kind} ${item.name}: ${item.problem}${item.detail == null ? "" : ` (${item.detail})`}`
+      );
   return lines;
 };
 export {
-  diagnosticLine,
-  errorLines,
-  hookLines,
-  manifestSummaryLines,
-  publishResultLines,
-  reportLines
+  errorLines
 };
 //# sourceMappingURL=output.mjs.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/cli/output.ts"],
-  "sourcesContent": ["import type { CompatibilityReportIface } from '@finalai/agent-definition/compatibility';\nimport type { DiagnosticIface } from '@finalai/agent-definition/compiler';\nimport {\n  findDynamicSlots,\n  formatProviderRef,\n  isDynamicSlot,\n  type AgentManifestIface,\n} from '@finalai/agent-provider';\nimport * as z from 'zod';\nimport { isClientError } from \"../agent-client/errors.mjs\";\nimport { diagnosticSchema, type PublishResultIface } from \"../agent-client/index.mjs\";\n\nexport interface OutputIface {\n  stdout: (line: string) => void;\n  stderr: (line: string) => void;\n}\n\nconst listOrNone = (items: readonly string[]): string =>\n  items.length === 0 ? 'none' : items.join(', ');\n\nexport const manifestSummaryLines = (manifest: AgentManifestIface): string[] => {\n  const lines = [`agent: ${manifest.identity.name}`];\n  if (manifest.identity.description != null)\n    lines.push(`description: ${manifest.identity.description}`);\n  lines.push(`harness: ${formatProviderRef(manifest.harness.harness)}`);\n  lines.push(\n    `mcp servers: ${\n      isDynamicSlot(manifest.mcpServers)\n        ? 'dynamic'\n        : listOrNone(manifest.mcpServers.map((server) => `${server.key} (${server.kind})`))\n    }`,\n  );\n  lines.push(\n    `sandboxes: ${\n      isDynamicSlot(manifest.sandboxes) ? 'dynamic' : listOrNone(Object.keys(manifest.sandboxes))\n    }`,\n  );\n  lines.push(\n    `base tools: ${listOrNone(\n      Object.entries(manifest.tools.base).map(\n        ([capability, binding]) => `${capability} \u2192 ${binding?.target ?? '?'}`,\n      ),\n    )}`,\n  );\n  lines.push(`channels: ${listOrNone(manifest.channels.map((channel) => channel.key))}`);\n  lines.push(\n    `schedules: ${listOrNone(\n      manifest.schedules.map(\n        (schedule) => `${schedule.key} (${schedule.cron}, ${schedule.timezone})`,\n      ),\n    )}`,\n  );\n  lines.push(`secrets: ${listOrNone(manifest.secrets)}`);\n  lines.push(`dynamic slots: ${listOrNone(findDynamicSlots(manifest).map((slot) => slot.path))}`);\n  lines.push(`bundle: ${manifest.bundle?.hash ?? 'none'}`);\n  return lines;\n};\n\nexport const hookLines = (manifest: AgentManifestIface): string[] =>\n  manifest.hooks.length === 0\n    ? ['hooks: none']\n    : [\n        'hooks:',\n        ...manifest.hooks.map(\n          (hook) => `  ${hook.slug} (${hook.export}): ${hook.events.join(', ')}`,\n        ),\n      ];\n\nexport const reportLines = (report: CompatibilityReportIface): string[] => [\n  `compatibility with ${formatProviderRef(report.harness)}: ${report.ok ? 'ok' : 'incompatible'}`,\n  ...report.rows.map((row) => `  ${row.item}: ${row.result} (${row.why})`),\n];\n\nexport const diagnosticLine = (item: DiagnosticIface): string =>\n  `${item.severity}: ${item.path == null ? '' : `${item.path}: `}${item.message} [${item.code}]`;\n\nconst errorDiagnosticsSchema = z.object({\n  error: z.object({\n    details: z.object({ diagnostics: z.array(diagnosticSchema) }).nullable(),\n  }),\n});\n\n// SDK errors with the server's compile diagnostics, when it sent any.\nexport const errorLines = (cause: unknown): string[] => {\n  if (!isClientError(cause))\n    return [`error: ${cause instanceof Error ? cause.message : String(cause)}`];\n  const lines = [`error: ${cause.message}${cause.status === 0 ? '' : ` (HTTP ${cause.status})`}`];\n  const parsed = errorDiagnosticsSchema.safeParse(cause.body);\n  for (const item of parsed.success ? (parsed.data.error.details?.diagnostics ?? []) : []) {\n    lines.push(`  ${item.severity}: ${item.file == null ? '' : `${item.file}: `}${item.message}`);\n  }\n  return lines;\n};\n\nexport const publishResultLines = (result: PublishResultIface): string[] => {\n  const revision = result.revision;\n  const lines = [\n    `${result.created ? 'published' : 'already published'}: revision ${revision.number} (${revision.id})`,\n    `commit: ${revision.commitSha ?? 'unknown'}`,\n    `bundle: ${revision.bundleHash ?? 'none'}`,\n  ];\n  for (const item of result.diagnostics) lines.push(`${item.severity}: ${item.message}`);\n  for (const channel of result.channels) {\n    lines.push(`channel ${channel.key} (${channel.bindingId}):`);\n    for (const route of channel.routes) {\n      lines.push(`  ${route.method} ${route.url ?? route.aliasUrl}`);\n      if (route.url != null) lines.push(`    alias: ${route.aliasUrl}`);\n    }\n    if (channel.webhookSecret != null)\n      lines.push(`  signing secret (shown once): ${channel.webhookSecret}`);\n  }\n  return lines;\n};\n"],
-  "mappings": "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",
+  "sourcesContent": ["import { isClientError, isRequirementsUnmetError } from \"../agent-client/errors.mjs\";\n\nexport interface OutputIface {\n  stdout: (line: string) => void;\n  stderr: (line: string) => void;\n}\n\n// An error as lines for stderr: the message and, for a refused request, its\n// status and anything the platform said was missing.\nexport const errorLines = (cause: unknown): string[] => {\n  if (!isClientError(cause))\n    return [`error: ${cause instanceof Error ? cause.message : String(cause)}`];\n  const lines = [`error: ${cause.message}${cause.status === 0 ? '' : ` (HTTP ${cause.status})`}`];\n  if (isRequirementsUnmetError(cause))\n    for (const item of cause.requirements)\n      lines.push(\n        `  ${item.kind} ${item.name}: ${item.problem}${item.detail == null ? '' : ` (${item.detail})`}`,\n      );\n  return lines;\n};\n"],
+  "mappings": "AAAA,SAAS,eAAe,gCAAgC;AASjD,MAAM,aAAa,CAAC,UAA6B;AACtD,MAAI,CAAC,cAAc,KAAK;AACtB,WAAO,CAAC,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC,EAAE;AAC5E,QAAM,QAAQ,CAAC,UAAU,MAAM,OAAO,GAAG,MAAM,WAAW,IAAI,KAAK,UAAU,MAAM,MAAM,GAAG,EAAE;AAC9F,MAAI,yBAAyB,KAAK;AAChC,eAAW,QAAQ,MAAM;AACvB,YAAM;AAAA,QACJ,KAAK,KAAK,IAAI,IAAI,KAAK,IAAI,KAAK,KAAK,OAAO,GAAG,KAAK,UAAU,OAAO,KAAK,KAAK,KAAK,MAAM,GAAG;AAAA,MAC/F;AACJ,SAAO;AACT;",
   "names": []
 }

package/dist/modules/harnesses.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/harnesses.ts"],
-  "sourcesContent": ["export * from '@finalai/final-agent-provider/harnesses';\n"],
-  "mappings": "AAAA,cAAc;",
+  "sourcesContent": ["// Harness settings builders for Final's harnesses (`serverlessPi`,\n// `claudeCode`, ...), the `FinalHarness` names, Final's harness and ACP\n// adapter definitions, and the inference sources a harness pays with\n// (`subscription`, `apiKey`, `finalCredits`, `harnessLogin`).\nexport * from '@finalai/final-agent-provider/harnesses';\n"],
+  "mappings": "AAIA,cAAc;",
   "names": []
 }

package/dist/modules/index.d.mts

@@ -1,3 +1 @@
 export * from "./public.mjs";
-export { compile } from "./compile.mjs";
-export type { CompatibilityReportIface, CompileOptionsIface, CompileResultIface, CompiledBundleIface, DiagnosticCode, DiagnosticIface, DiagnosticSeverity, HarnessDescriptionContextIface, } from "./compile.mjs";

package/dist/modules/index.mjs

@@ -1,6 +1,2 @@
 export * from "./public.mjs";
-import { compile } from "./compile.mjs";
-export {
-  compile
-};
 //# sourceMappingURL=index.mjs.map

package/dist/modules/index.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/index.ts"],
-  "sourcesContent": ["export * from \"./public.mjs\";\n\n// Node compiler entrypoint.\nexport { compile } from \"./compile.mjs\";\nexport type {\n  CompatibilityReportIface,\n  CompileOptionsIface,\n  CompileResultIface,\n  CompiledBundleIface,\n  DiagnosticCode,\n  DiagnosticIface,\n  DiagnosticSeverity,\n  HarnessDescriptionContextIface,\n} from \"./compile.mjs\";\n"],
-  "mappings": "AAAA,cAAc;AAGd,SAAS,eAAe;",
+  "sourcesContent": ["export * from \"./public.mjs\";\n"],
+  "mappings": "AAAA,cAAc;",
   "names": []
 }

package/dist/modules/integrations.d.mts

@@ -0,0 +1,24 @@
+import { CredentialScope, IntegrationAuthKind, type IntegrationAuthInput } from '@finalai/agent-protocol/agent-platform';
+export { CredentialScope, IntegrationAuthKind, type IntegrationAuthInput };
+/**
+ * OAuth against the server's authorization server: each person signs in with
+ * their own account (`personal`, the default), or one sign-in serves the
+ * whole project (`shared`).
+ */
+export declare const oauth: (args?: {
+    credential?: CredentialScope | `${CredentialScope}`;
+    scopes?: string[];
+}) => IntegrationAuthInput;
+/** A project secret, by name, sent as `Authorization: Bearer <secret>` or in `header`. */
+export declare const secret: (name: string, args?: {
+    header?: string;
+}) => IntegrationAuthInput;
+/**
+ * A short-lived signed assertion of the calling session, which the server
+ * verifies against Final's published keys. `scopes` groups what it grants:
+ * `{ api: ['session:requirements'], reach: ['session'] }`.
+ */
+export declare const platformIdentity: (scopes?: Record<string, string[]>) => IntegrationAuthInput;
+/** No authentication. */
+export declare const noAuth: () => IntegrationAuthInput;
+export { finalGateway } from '@finalai/final-agent-provider/integrations';

package/dist/modules/integrations.mjs

@@ -0,0 +1,30 @@
+import {
+  CredentialScope,
+  IntegrationAuthKind
+} from "@finalai/agent-protocol/agent-platform";
+const oauth = (args = {}) => ({
+  kind: IntegrationAuthKind.OAuth,
+  credential: args.credential === "shared" ? CredentialScope.Shared : CredentialScope.Personal,
+  ...args.scopes == null ? {} : { scopes: args.scopes }
+});
+const secret = (name, args = {}) => ({
+  kind: IntegrationAuthKind.Secret,
+  secret: name,
+  ...args.header == null ? {} : { header: args.header }
+});
+const platformIdentity = (scopes = {}) => ({
+  kind: IntegrationAuthKind.PlatformIdentity,
+  scopes
+});
+const noAuth = () => ({ kind: IntegrationAuthKind.None });
+import { finalGateway } from "@finalai/final-agent-provider/integrations";
+export {
+  CredentialScope,
+  IntegrationAuthKind,
+  finalGateway,
+  noAuth,
+  oauth,
+  platformIdentity,
+  secret
+};
+//# sourceMappingURL=integrations.mjs.map

package/dist/modules/integrations.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/integrations.ts"],
+  "sourcesContent": ["import {\n  CredentialScope,\n  IntegrationAuthKind,\n  type IntegrationAuthInput,\n} from '@finalai/agent-protocol/agent-platform';\n\n// How calls to an integration authenticate, for `project.integrations.create`.\n// A person's own sign-in is runtime state: the platform asks for it on first\n// use, never the agent.\n\nexport { CredentialScope, IntegrationAuthKind, type IntegrationAuthInput };\n\n/**\n * OAuth against the server's authorization server: each person signs in with\n * their own account (`personal`, the default), or one sign-in serves the\n * whole project (`shared`).\n */\nexport const oauth = (\n  args: { credential?: CredentialScope | `${CredentialScope}`; scopes?: string[] } = {},\n): IntegrationAuthInput => ({\n  kind: IntegrationAuthKind.OAuth,\n  credential: args.credential === 'shared' ? CredentialScope.Shared : CredentialScope.Personal,\n  ...(args.scopes == null ? {} : { scopes: args.scopes }),\n});\n\n/** A project secret, by name, sent as `Authorization: Bearer <secret>` or in `header`. */\nexport const secret = (name: string, args: { header?: string } = {}): IntegrationAuthInput => ({\n  kind: IntegrationAuthKind.Secret,\n  secret: name,\n  ...(args.header == null ? {} : { header: args.header }),\n});\n\n/**\n * A short-lived signed assertion of the calling session, which the server\n * verifies against Final's published keys. `scopes` groups what it grants:\n * `{ api: ['session:requirements'], reach: ['session'] }`.\n */\nexport const platformIdentity = (scopes: Record<string, string[]> = {}): IntegrationAuthInput => ({\n  kind: IntegrationAuthKind.PlatformIdentity,\n  scopes,\n});\n\n/** No authentication. */\nexport const noAuth = (): IntegrationAuthInput => ({ kind: IntegrationAuthKind.None });\n\nexport { finalGateway } from '@finalai/final-agent-provider/integrations';\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AAaA,MAAM,QAAQ,CACnB,OAAmF,CAAC,OAC1D;AAAA,EAC1B,MAAM,oBAAoB;AAAA,EAC1B,YAAY,KAAK,eAAe,WAAW,gBAAgB,SAAS,gBAAgB;AAAA,EACpF,GAAI,KAAK,UAAU,OAAO,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO;AACvD;AAGO,MAAM,SAAS,CAAC,MAAc,OAA4B,CAAC,OAA6B;AAAA,EAC7F,MAAM,oBAAoB;AAAA,EAC1B,QAAQ;AAAA,EACR,GAAI,KAAK,UAAU,OAAO,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO;AACvD;AAOO,MAAM,mBAAmB,CAAC,SAAmC,CAAC,OAA6B;AAAA,EAChG,MAAM,oBAAoB;AAAA,EAC1B;AACF;AAGO,MAAM,SAAS,OAA6B,EAAE,MAAM,oBAAoB,KAAK;AAEpF,SAAS,oBAAoB;",
+  "names": []
+}

package/dist/modules/public.d.mts

@@ -1,10 +1,10 @@
-export { CredentialOwner, CredentialPayer, DELETE, GET, HookEvent, POST, PUT, SandboxWire, WS, always, baseTools, credentials, defineAgent, defineChannel, disableChannel, defineDynamic, defineHarness, defineHostedConnection, defineHook, defineInstructions, defineMcpClientConnection, defineSandbox, defineSandboxProvider, defineSchedule, defineSkill, defineTool, harnessHost, never, toolResultFrom, whenInput, } from "./authoring/index.mjs";
-export type { AgentDefinitionInputIface, AgentSessionInfoIface, ApprovalPolicyIface, AuthoredChannelDefinitionIface, AuthoredHarnessCloseContextIface, AuthoredHarnessDescriptionIface, AuthoredHarnessEndpointIface, AuthoredHarnessHealthIface, AuthoredHarnessIface, AuthoredHarnessOpenArgsIface, AuthoredHarnessRefContextIface, AuthoredHarnessResumeArgsIface, BaseToolsValueIface, ConversationInfoIface, CredentialNode, CredentialPolicyIface, DefinedAuthoredHarnessIface, DefinedToolIface, DynamicDefinitionIface, DynamicResolveContextIface, DynamicSentinelIface, FinalPlatformClientIface, HarnessHostIface, HookContextIface, HookDefinitionIface, HookEventIface, HostedConnectionDefinitionIface, McpClientConnectionDefinitionIface, SandboxSelectorContextIface, ScheduleInputIface, SkillDefinitionIface, ToolContextIface, ToolDefinitionIface, } from "./authoring/index.mjs";
-export * from "./authoring/providers.mjs";
-export type { AgentAvatarIface, AvatarMedia, AvatarState, AgentManifestIface, ChannelDefinitionIface, ChannelCredentialRef, ChannelCredentialHandle, ChannelCredentialsIface, ChannelCredentialSocketIface, ChannelReceiveContextIface, ChannelEventContextIface, ConversationHandle, PersonHandle, PlaceRef, PrincipalRef, RouteDefinitionIface, RoomPlatformIface, ChannelSocketIface, HarnessDescriptionIface, HarnessEndpointIface, HarnessIface, HarnessSessionRefIface, HostedBindingsIface, McpChannelIface, NetworkSandboxSessionIface, ResolvedAgentManifestIface, SandboxMcpEndpoint, SandboxPrepareContextIface, SandboxProcessIface, SandboxProviderHandleIface, SandboxProviderIface, SandboxProviderImplementationIface, SandboxSessionIface, SandboxStartContextIface, ScreenSessionIface, } from '@finalai/agent-provider';
-export { requireHostedBinding } from '@finalai/agent-provider';
-export { validateHostedBindings } from '@finalai/agent-definition';
-export type { HostedBindingRequirementIface } from '@finalai/agent-provider';
-export { defineFinalConnection } from '@finalai/final-agent-provider/connections';
-export type { FinalConnectionDefinitionIface, FinalHostedConnectionDefinitionIface, } from '@finalai/final-agent-provider/connections';
-export { bundleRef, ChannelCredentialKind, ChannelSigningAlgorithm, ChannelSignatureEncoding, ChannelOAuthClientAuthentication, } from "./authoring/index.mjs";
+export * from '@finalai/agent-definition/authoring';
+export { documentOf } from '@finalai/agent-definition';
+export type { AgentAvatarIface, AvatarMedia, AvatarState } from '@finalai/agent-protocol';
+export type { ChannelCredentialsIface, ChannelDefinitionIface, ChannelEventContextIface, ChannelIngressContextIface, ChannelIngressIface, ChannelReceiveContextIface, ChannelRequireIface, ChannelSocketIface, ConversationHandle, PersonHandle, PlaceRef, PrincipalRef, RouteDefinitionIface, } from '@finalai/agent-provider';
+export type { AgentDocumentIface } from '@finalai/agent-provider/document';
+export { HarnessFeature } from '@finalai/agent-provider/document';
+export { PermissionLevel, InferenceSourceKind } from '@finalai/agent-protocol/agent-platform';
+export { AcpTransport, CredentialDelivery, McpTransportKind, PromptWhileRunning, SandboxWire, } from '@finalai/agent-provider/harness';
+export { AdapterConfigurationDelivery, FinalExtension, RuntimeKind, harnessDefinitionHash, acpAdapterDefinitionHash, type AcpAdapterDefinitionIface, type AcpAdapterDefinitionInputIface, type HarnessDefinitionIface, type HarnessDefinitionInputIface, } from '@finalai/agent-provider/harness-definition';
+export type { HarnessProviderCloseArgsIface, HarnessProviderContextIface, HarnessProviderEndpointResultIface, HarnessProviderIface, HarnessProviderOpenArgsIface, HarnessProviderOpenResultIface, HarnessProviderRefusalIface, HarnessProviderRefArgsIface, HarnessProviderResumeArgsIface, } from '@finalai/agent-provider/harness-provider';

package/dist/modules/public.mjs

@@ -1,84 +1,35 @@
+export * from "@finalai/agent-definition/authoring";
+import { documentOf } from "@finalai/agent-definition";
+import { HarnessFeature } from "@finalai/agent-provider/document";
+import { PermissionLevel, InferenceSourceKind } from "@finalai/agent-protocol/agent-platform";
 import {
-  CredentialOwner,
-  CredentialPayer,
-  DELETE,
-  GET,
-  HookEvent,
-  POST,
-  PUT,
-  SandboxWire,
-  WS,
-  always,
-  baseTools,
-  credentials,
-  defineAgent,
-  defineChannel,
-  disableChannel,
-  defineDynamic,
-  defineHarness,
-  defineHostedConnection,
-  defineHook,
-  defineInstructions,
-  defineMcpClientConnection,
-  defineSandbox,
-  defineSandboxProvider,
-  defineSchedule,
-  defineSkill,
-  defineTool,
-  harnessHost,
-  never,
-  toolResultFrom,
-  whenInput
-} from "./authoring/index.mjs";
-export * from "./authoring/providers.mjs";
-import { requireHostedBinding } from "@finalai/agent-provider";
-import { validateHostedBindings } from "@finalai/agent-definition";
-import { defineFinalConnection } from "@finalai/final-agent-provider/connections";
+  AcpTransport,
+  CredentialDelivery,
+  McpTransportKind,
+  PromptWhileRunning,
+  SandboxWire
+} from "@finalai/agent-provider/harness";
 import {
-  bundleRef,
-  ChannelCredentialKind,
-  ChannelSigningAlgorithm,
-  ChannelSignatureEncoding,
-  ChannelOAuthClientAuthentication
-} from "./authoring/index.mjs";
+  AdapterConfigurationDelivery,
+  FinalExtension,
+  RuntimeKind,
+  harnessDefinitionHash,
+  acpAdapterDefinitionHash
+} from "@finalai/agent-provider/harness-definition";
 export {
-  ChannelCredentialKind,
-  ChannelOAuthClientAuthentication,
-  ChannelSignatureEncoding,
-  ChannelSigningAlgorithm,
-  CredentialOwner,
-  CredentialPayer,
-  DELETE,
-  GET,
-  HookEvent,
-  POST,
-  PUT,
+  AcpTransport,
+  AdapterConfigurationDelivery,
+  CredentialDelivery,
+  FinalExtension,
+  HarnessFeature,
+  InferenceSourceKind,
+  McpTransportKind,
+  PermissionLevel,
+  PromptWhileRunning,
+  RuntimeKind,
   SandboxWire,
-  WS,
-  always,
-  baseTools,
-  bundleRef,
-  credentials,
-  defineAgent,
-  defineChannel,
-  defineDynamic,
-  defineFinalConnection,
-  defineHarness,
-  defineHook,
-  defineHostedConnection,
-  defineInstructions,
-  defineMcpClientConnection,
-  defineSandbox,
-  defineSandboxProvider,
-  defineSchedule,
-  defineSkill,
-  defineTool,
-  disableChannel,
-  harnessHost,
-  never,
-  requireHostedBinding,
-  toolResultFrom,
-  validateHostedBindings,
-  whenInput
+  acpAdapterDefinitionHash,
+  documentOf,
+  harnessDefinitionHash
 };
 //# sourceMappingURL=public.mjs.map

package/dist/modules/public.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/public.ts"],
-  "sourcesContent": ["// Agent authoring.\nexport {\n  CredentialOwner,\n  CredentialPayer,\n  DELETE,\n  GET,\n  HookEvent,\n  POST,\n  PUT,\n  SandboxWire,\n  WS,\n  always,\n  baseTools,\n  credentials,\n  defineAgent,\n  defineChannel,\n  disableChannel,\n  defineDynamic,\n  defineHarness,\n  defineHostedConnection,\n  defineHook,\n  defineInstructions,\n  defineMcpClientConnection,\n  defineSandbox,\n  defineSandboxProvider,\n  defineSchedule,\n  defineSkill,\n  defineTool,\n  harnessHost,\n  never,\n  toolResultFrom,\n  whenInput,\n} from \"./authoring/index.mjs\";\nexport type {\n  AgentDefinitionInputIface,\n  AgentSessionInfoIface,\n  ApprovalPolicyIface,\n  AuthoredChannelDefinitionIface,\n  AuthoredHarnessCloseContextIface,\n  AuthoredHarnessDescriptionIface,\n  AuthoredHarnessEndpointIface,\n  AuthoredHarnessHealthIface,\n  AuthoredHarnessIface,\n  AuthoredHarnessOpenArgsIface,\n  AuthoredHarnessRefContextIface,\n  AuthoredHarnessResumeArgsIface,\n  BaseToolsValueIface,\n  ConversationInfoIface,\n  CredentialNode,\n  CredentialPolicyIface,\n  DefinedAuthoredHarnessIface,\n  DefinedToolIface,\n  DynamicDefinitionIface,\n  DynamicResolveContextIface,\n  DynamicSentinelIface,\n  FinalPlatformClientIface,\n  HarnessHostIface,\n  HookContextIface,\n  HookDefinitionIface,\n  HookEventIface,\n  HostedConnectionDefinitionIface,\n  McpClientConnectionDefinitionIface,\n  SandboxSelectorContextIface,\n  ScheduleInputIface,\n  SkillDefinitionIface,\n  ToolContextIface,\n  ToolDefinitionIface,\n} from \"./authoring/index.mjs\";\nexport * from \"./authoring/providers.mjs\";\n\nexport type {\n  AgentAvatarIface,\n  AvatarMedia,\n  AvatarState,\n  AgentManifestIface,\n  ChannelDefinitionIface,\n  ChannelCredentialRef,\n  ChannelCredentialHandle,\n  ChannelCredentialsIface,\n  ChannelCredentialSocketIface,\n  ChannelReceiveContextIface,\n  ChannelEventContextIface,\n  ConversationHandle,\n  PersonHandle,\n  PlaceRef,\n  PrincipalRef,\n  RouteDefinitionIface,\n  RoomPlatformIface,\n  ChannelSocketIface,\n  HarnessDescriptionIface,\n  HarnessEndpointIface,\n  HarnessIface,\n  HarnessSessionRefIface,\n  HostedBindingsIface,\n  McpChannelIface,\n  NetworkSandboxSessionIface,\n  ResolvedAgentManifestIface,\n  SandboxMcpEndpoint,\n  SandboxPrepareContextIface,\n  SandboxProcessIface,\n  SandboxProviderHandleIface,\n  SandboxProviderIface,\n  SandboxProviderImplementationIface,\n  SandboxSessionIface,\n  SandboxStartContextIface,\n  ScreenSessionIface,\n} from '@finalai/agent-provider';\n\nexport { requireHostedBinding } from '@finalai/agent-provider';\nexport { validateHostedBindings } from '@finalai/agent-definition';\nexport type { HostedBindingRequirementIface } from '@finalai/agent-provider';\n\nexport { defineFinalConnection } from '@finalai/final-agent-provider/connections';\nexport type {\n  FinalConnectionDefinitionIface,\n  FinalHostedConnectionDefinitionIface,\n} from '@finalai/final-agent-provider/connections';\n\nexport {\n  bundleRef,\n  ChannelCredentialKind,\n  ChannelSigningAlgorithm,\n  ChannelSignatureEncoding,\n  ChannelOAuthClientAuthentication,\n} from \"./authoring/index.mjs\";\n"],
-  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAoCP,cAAc;AAwCd,SAAS,4BAA4B;AACrC,SAAS,8BAA8B;AAGvC,SAAS,6BAA6B;AAMtC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;",
+  "sourcesContent": ["// Agent authoring: an agent is a value that lists every part explicitly and\n// states what it requires. `documentOf(agent)` is its document (data).\nexport * from '@finalai/agent-definition/authoring';\nexport { documentOf } from '@finalai/agent-definition';\n\nexport type { AgentAvatarIface, AvatarMedia, AvatarState } from '@finalai/agent-protocol';\nexport type {\n  ChannelCredentialsIface,\n  ChannelDefinitionIface,\n  ChannelEventContextIface,\n  ChannelIngressContextIface,\n  ChannelIngressIface,\n  ChannelReceiveContextIface,\n  ChannelRequireIface,\n  ChannelSocketIface,\n  ConversationHandle,\n  PersonHandle,\n  PlaceRef,\n  PrincipalRef,\n  RouteDefinitionIface,\n} from '@finalai/agent-provider';\nexport type { AgentDocumentIface } from '@finalai/agent-provider/document';\n\n// Harness and ACP adapter definitions (defineHarness, defineAcpAdapter) and\n// the values they take.\nexport { HarnessFeature } from '@finalai/agent-provider/document';\nexport { PermissionLevel, InferenceSourceKind } from '@finalai/agent-protocol/agent-platform';\nexport {\n  AcpTransport,\n  CredentialDelivery,\n  McpTransportKind,\n  PromptWhileRunning,\n  SandboxWire,\n} from '@finalai/agent-provider/harness';\nexport {\n  AdapterConfigurationDelivery,\n  FinalExtension,\n  RuntimeKind,\n  harnessDefinitionHash,\n  acpAdapterDefinitionHash,\n  type AcpAdapterDefinitionIface,\n  type AcpAdapterDefinitionInputIface,\n  type HarnessDefinitionIface,\n  type HarnessDefinitionInputIface,\n} from '@finalai/agent-provider/harness-definition';\nexport type {\n  HarnessProviderCloseArgsIface,\n  HarnessProviderContextIface,\n  HarnessProviderEndpointResultIface,\n  HarnessProviderIface,\n  HarnessProviderOpenArgsIface,\n  HarnessProviderOpenResultIface,\n  HarnessProviderRefusalIface,\n  HarnessProviderRefArgsIface,\n  HarnessProviderResumeArgsIface,\n} from '@finalai/agent-provider/harness-provider';\n"],
+  "mappings": "AAEA,cAAc;AACd,SAAS,kBAAkB;AAsB3B,SAAS,sBAAsB;AAC/B,SAAS,iBAAiB,2BAA2B;AACrD;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAKK;",
   "names": []
 }

package/dist/modules/sandboxes.d.mts

@@ -1 +1,3 @@
 export * from '@finalai/final-agent-provider/sandboxes';
+export { defineSandboxSetup } from '@finalai/agent-provider/sandbox/setup';
+export type { SandboxSetupIface, SandboxSetupInputIface, } from '@finalai/agent-provider/sandbox/setup';

package/dist/modules/sandboxes.mjs

@@ -1,2 +1,6 @@
 export * from "@finalai/final-agent-provider/sandboxes";
+import { defineSandboxSetup } from "@finalai/agent-provider/sandbox/setup";
+export {
+  defineSandboxSetup
+};
 //# sourceMappingURL=sandboxes.mjs.map

package/dist/modules/sandboxes.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/sandboxes.ts"],
-  "sourcesContent": ["export * from '@finalai/final-agent-provider/sandboxes';\n"],
-  "mappings": "AAAA,cAAc;",
+  "sourcesContent": ["// Sandbox environments from Final's providers (`computer`, `device`), and the\n// provider-neutral setup of what should be on a machine.\nexport * from '@finalai/final-agent-provider/sandboxes';\nexport { defineSandboxSetup } from '@finalai/agent-provider/sandbox/setup';\nexport type {\n  SandboxSetupIface,\n  SandboxSetupInputIface,\n} from '@finalai/agent-provider/sandbox/setup';\n"],
+  "mappings": "AAEA,cAAc;AACd,SAAS,0BAA0B;",
   "names": []
 }

package/dist/modules/verify.d.mts

@@ -0,0 +1 @@
+export * from '@finalai/agent-protocol/identity';

package/dist/modules/verify.mjs

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

package/dist/modules/verify.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/verify.ts"],
+  "sourcesContent": ["// `@finalai/agents/verify`: verifiers for the tokens the agent platform and\n// its authorization server sign (platform-identity assertions, access tokens\n// and human-input attestations). WebCrypto only, so they run in any modern runtime.\nexport * from '@finalai/agent-protocol/identity';\n"],
+  "mappings": "AAGA,cAAc;",
+  "names": []
+}

package/dist/modules/webhooks.d.mts

@@ -0,0 +1,37 @@
+import { type EventDeliveryIface } from '@finalai/agent-protocol/agent-platform/events';
+/** How far a delivery's timestamp may be from the receiver's clock. */
+export declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS: number;
+/** Why a delivery was refused. */
+export declare enum WebhookRefusal {
+    MissingHeaders = "missing_headers",
+    StaleTimestamp = "stale_timestamp",
+    BadSignature = "bad_signature",
+    InvalidPayload = "invalid_payload"
+}
+export type WebhookVerificationType = {
+    ok: true;
+    id: string;
+    delivery: EventDeliveryIface;
+} | {
+    ok: false;
+    refusal: WebhookRefusal;
+};
+/** A `Headers`, or a plain record such as Node's `IncomingHttpHeaders`. */
+export type WebhookHeadersInput = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+export interface VerifyWebhookArgsIface {
+    /** The request body exactly as received; parsing and re-serializing breaks the signature. */
+    payload: string;
+    headers: WebhookHeadersInput;
+    /** The subscription's `signingSecret`. */
+    secret: string;
+    toleranceSeconds?: number;
+    /** Seam for the receiver's clock, in epoch ms. */
+    now?: number;
+}
+/**
+ * Checks a delivery's signature and timestamp, then parses its body. Event
+ * kinds this package predates read as unrecognized events rather than failing.
+ * A delivery may repeat: deduplicate by the returned `id` (and events by theirs).
+ */
+export declare const verifyWebhook: (args: VerifyWebhookArgsIface) => Promise<WebhookVerificationType>;
+export { EventSubscriptionState, PlatformEventKind, WEBHOOK_ID_HEADER, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, type EventDeliveryIface, type PlatformEventType, } from '@finalai/agent-protocol/agent-platform/events';

package/dist/modules/webhooks.mjs

@@ -0,0 +1,100 @@
+import {
+  eventDeliverySchema,
+  WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER
+} from "@finalai/agent-protocol/agent-platform/events";
+const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 5 * 60;
+const SECRET_PREFIX = "whsec_";
+const SIGNATURE_VERSION = "v1";
+var WebhookRefusal = /* @__PURE__ */ ((WebhookRefusal2) => {
+  WebhookRefusal2["MissingHeaders"] = "missing_headers";
+  WebhookRefusal2["StaleTimestamp"] = "stale_timestamp";
+  WebhookRefusal2["BadSignature"] = "bad_signature";
+  WebhookRefusal2["InvalidPayload"] = "invalid_payload";
+  return WebhookRefusal2;
+})(WebhookRefusal || {});
+const headerOf = (headers, name) => {
+  if (headers instanceof Headers) return headers.get(name);
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== name || value == null) continue;
+    return typeof value === "string" ? value : value[0] ?? null;
+  }
+  return null;
+};
+const base64Bytes = (text) => {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(text)) return null;
+  try {
+    const binary = atob(text);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+    return bytes;
+  } catch {
+    return null;
+  }
+};
+const refused = (refusal) => ({
+  ok: false,
+  refusal
+});
+const verifyWebhook = async (args) => {
+  const id = headerOf(args.headers, WEBHOOK_ID_HEADER);
+  const timestamp = headerOf(args.headers, WEBHOOK_TIMESTAMP_HEADER);
+  const signatures = headerOf(args.headers, WEBHOOK_SIGNATURE_HEADER);
+  if (id == null || timestamp == null || signatures == null || !/^\d{1,12}$/u.test(timestamp))
+    return refused("missing_headers" /* MissingHeaders */);
+  const nowSeconds = Math.floor((args.now ?? Date.now()) / 1e3);
+  const tolerance = args.toleranceSeconds ?? DEFAULT_WEBHOOK_TOLERANCE_SECONDS;
+  if (Math.abs(nowSeconds - Number(timestamp)) > tolerance)
+    return refused("stale_timestamp" /* StaleTimestamp */);
+  const secret = base64Bytes(
+    args.secret.startsWith(SECRET_PREFIX) ? args.secret.slice(SECRET_PREFIX.length) : args.secret
+  );
+  if (secret == null || secret.length === 0) return refused("bad_signature" /* BadSignature */);
+  const key = await globalThis.crypto.subtle.importKey(
+    "raw",
+    secret,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  const signed = new TextEncoder().encode(`${id}.${timestamp}.${args.payload}`);
+  let matched = false;
+  for (const entry of signatures.split(" ")) {
+    const comma = entry.indexOf(",");
+    if (comma < 0 || entry.slice(0, comma) !== SIGNATURE_VERSION) continue;
+    const signature = base64Bytes(entry.slice(comma + 1));
+    if (signature != null && await globalThis.crypto.subtle.verify("HMAC", key, signature, signed)) {
+      matched = true;
+      break;
+    }
+  }
+  if (!matched) return refused("bad_signature" /* BadSignature */);
+  let body;
+  try {
+    body = JSON.parse(args.payload);
+  } catch {
+    return refused("invalid_payload" /* InvalidPayload */);
+  }
+  const delivery = eventDeliverySchema.safeParse(body);
+  if (!delivery.success) return refused("invalid_payload" /* InvalidPayload */);
+  return { ok: true, id, delivery: delivery.data };
+};
+import {
+  EventSubscriptionState,
+  PlatformEventKind,
+  WEBHOOK_ID_HEADER as WEBHOOK_ID_HEADER2,
+  WEBHOOK_SIGNATURE_HEADER as WEBHOOK_SIGNATURE_HEADER2,
+  WEBHOOK_TIMESTAMP_HEADER as WEBHOOK_TIMESTAMP_HEADER2
+} from "@finalai/agent-protocol/agent-platform/events";
+export {
+  DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
+  EventSubscriptionState,
+  PlatformEventKind,
+  WEBHOOK_ID_HEADER2 as WEBHOOK_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER2 as WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER2 as WEBHOOK_TIMESTAMP_HEADER,
+  WebhookRefusal,
+  verifyWebhook
+};
+//# sourceMappingURL=webhooks.mjs.map

package/dist/modules/webhooks.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/webhooks.ts"],
+  "sourcesContent": ["// `@finalai/agents/webhooks`: verifies an event subscription's deliveries.\n// Deliveries are signed per Standard Webhooks (`webhook-id`,\n// `webhook-timestamp`, `webhook-signature: v1,<base64 HMAC-SHA256>`), so any\n// Standard Webhooks verifier works too. WebCrypto only: runs in Node, Workers,\n// Deno and browsers.\n\nimport {\n  eventDeliverySchema,\n  WEBHOOK_ID_HEADER,\n  WEBHOOK_SIGNATURE_HEADER,\n  WEBHOOK_TIMESTAMP_HEADER,\n  type EventDeliveryIface,\n} from '@finalai/agent-protocol/agent-platform/events';\n\n/** How far a delivery's timestamp may be from the receiver's clock. */\nexport const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 5 * 60;\n\nconst SECRET_PREFIX = 'whsec_';\n\nconst SIGNATURE_VERSION = 'v1';\n\n/** Why a delivery was refused. */\nexport enum WebhookRefusal {\n  // A `webhook-*` header is missing or malformed.\n  MissingHeaders = 'missing_headers',\n  // The timestamp is outside the tolerance (a replay, or a skewed clock).\n  StaleTimestamp = 'stale_timestamp',\n  // No `v1` signature matches the body under the secret.\n  BadSignature = 'bad_signature',\n  // The signature matches, but the body is not a delivery.\n  InvalidPayload = 'invalid_payload',\n}\n\nexport type WebhookVerificationType =\n  | { ok: true; id: string; delivery: EventDeliveryIface }\n  | { ok: false; refusal: WebhookRefusal };\n\n/** A `Headers`, or a plain record such as Node's `IncomingHttpHeaders`. */\nexport type WebhookHeadersInput =\n  | Headers\n  | Readonly<Record<string, string | readonly string[] | undefined>>;\n\nexport interface VerifyWebhookArgsIface {\n  /** The request body exactly as received; parsing and re-serializing breaks the signature. */\n  payload: string;\n  headers: WebhookHeadersInput;\n  /** The subscription's `signingSecret`. */\n  secret: string;\n  toleranceSeconds?: number;\n  /** Seam for the receiver's clock, in epoch ms. */\n  now?: number;\n}\n\nconst headerOf = (headers: WebhookHeadersInput, name: string): string | null => {\n  if (headers instanceof Headers) return headers.get(name);\n  for (const [key, value] of Object.entries(headers)) {\n    if (key.toLowerCase() !== name || value == null) continue;\n    return typeof value === 'string' ? value : (value[0] ?? null);\n  }\n  return null;\n};\n\nconst base64Bytes = (text: string): Uint8Array<ArrayBuffer> | null => {\n  if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(text)) return null;\n  try {\n    const binary = atob(text);\n    const bytes = new Uint8Array(new ArrayBuffer(binary.length));\n    for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);\n    return bytes;\n  } catch {\n    return null;\n  }\n};\n\nconst refused = (refusal: WebhookRefusal): { ok: false; refusal: WebhookRefusal } => ({\n  ok: false,\n  refusal,\n});\n\n/**\n * Checks a delivery's signature and timestamp, then parses its body. Event\n * kinds this package predates read as unrecognized events rather than failing.\n * A delivery may repeat: deduplicate by the returned `id` (and events by theirs).\n */\nexport const verifyWebhook = async (\n  args: VerifyWebhookArgsIface,\n): Promise<WebhookVerificationType> => {\n  const id = headerOf(args.headers, WEBHOOK_ID_HEADER);\n  const timestamp = headerOf(args.headers, WEBHOOK_TIMESTAMP_HEADER);\n  const signatures = headerOf(args.headers, WEBHOOK_SIGNATURE_HEADER);\n  if (id == null || timestamp == null || signatures == null || !/^\\d{1,12}$/u.test(timestamp))\n    return refused(WebhookRefusal.MissingHeaders);\n  const nowSeconds = Math.floor((args.now ?? Date.now()) / 1000);\n  const tolerance = args.toleranceSeconds ?? DEFAULT_WEBHOOK_TOLERANCE_SECONDS;\n  if (Math.abs(nowSeconds - Number(timestamp)) > tolerance)\n    return refused(WebhookRefusal.StaleTimestamp);\n\n  const secret = base64Bytes(\n    args.secret.startsWith(SECRET_PREFIX) ? args.secret.slice(SECRET_PREFIX.length) : args.secret,\n  );\n  if (secret == null || secret.length === 0) return refused(WebhookRefusal.BadSignature);\n  const key = await globalThis.crypto.subtle.importKey(\n    'raw',\n    secret,\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['verify'],\n  );\n  const signed = new TextEncoder().encode(`${id}.${timestamp}.${args.payload}`);\n  let matched = false;\n  for (const entry of signatures.split(' ')) {\n    const comma = entry.indexOf(',');\n    if (comma < 0 || entry.slice(0, comma) !== SIGNATURE_VERSION) continue;\n    const signature = base64Bytes(entry.slice(comma + 1));\n    // `verify` compares in constant time.\n    if (\n      signature != null &&\n      (await globalThis.crypto.subtle.verify('HMAC', key, signature, signed))\n    ) {\n      matched = true;\n      break;\n    }\n  }\n  if (!matched) return refused(WebhookRefusal.BadSignature);\n\n  let body: unknown;\n  try {\n    body = JSON.parse(args.payload);\n  } catch {\n    return refused(WebhookRefusal.InvalidPayload);\n  }\n  const delivery = eventDeliverySchema.safeParse(body);\n  if (!delivery.success) return refused(WebhookRefusal.InvalidPayload);\n  return { ok: true, id, delivery: delivery.data };\n};\n\nexport {\n  EventSubscriptionState,\n  PlatformEventKind,\n  WEBHOOK_ID_HEADER,\n  WEBHOOK_SIGNATURE_HEADER,\n  WEBHOOK_TIMESTAMP_HEADER,\n  type EventDeliveryIface,\n  type PlatformEventType,\n} from '@finalai/agent-protocol/agent-platform/events';\n"],
+  "mappings": "AAMA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAGA,MAAM,oCAAoC,IAAI;AAErD,MAAM,gBAAgB;AAEtB,MAAM,oBAAoB;AAGnB,IAAK,iBAAL,kBAAKA,oBAAL;AAEL,EAAAA,gBAAA,oBAAiB;AAEjB,EAAAA,gBAAA,oBAAiB;AAEjB,EAAAA,gBAAA,kBAAe;AAEf,EAAAA,gBAAA,oBAAiB;AARP,SAAAA;AAAA,GAAA;AA+BZ,MAAM,WAAW,CAAC,SAA8B,SAAgC;AAC9E,MAAI,mBAAmB,QAAS,QAAO,QAAQ,IAAI,IAAI;AACvD,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,QAAI,IAAI,YAAY,MAAM,QAAQ,SAAS,KAAM;AACjD,WAAO,OAAO,UAAU,WAAW,QAAS,MAAM,CAAC,KAAK;AAAA,EAC1D;AACA,SAAO;AACT;AAEA,MAAM,cAAc,CAAC,SAAiD;AACpE,MAAI,CAAC,0BAA0B,KAAK,IAAI,EAAG,QAAO;AAClD,MAAI;AACF,UAAM,SAAS,KAAK,IAAI;AACxB,UAAM,QAAQ,IAAI,WAAW,IAAI,YAAY,OAAO,MAAM,CAAC;AAC3D,aAAS,QAAQ,GAAG,QAAQ,OAAO,QAAQ,SAAS,EAAG,OAAM,KAAK,IAAI,OAAO,WAAW,KAAK;AAC7F,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,MAAM,UAAU,CAAC,aAAqE;AAAA,EACpF,IAAI;AAAA,EACJ;AACF;AAOO,MAAM,gBAAgB,OAC3B,SACqC;AACrC,QAAM,KAAK,SAAS,KAAK,SAAS,iBAAiB;AACnD,QAAM,YAAY,SAAS,KAAK,SAAS,wBAAwB;AACjE,QAAM,aAAa,SAAS,KAAK,SAAS,wBAAwB;AAClE,MAAI,MAAM,QAAQ,aAAa,QAAQ,cAAc,QAAQ,CAAC,cAAc,KAAK,SAAS;AACxF,WAAO,QAAQ,sCAA6B;AAC9C,QAAM,aAAa,KAAK,OAAO,KAAK,OAAO,KAAK,IAAI,KAAK,GAAI;AAC7D,QAAM,YAAY,KAAK,oBAAoB;AAC3C,MAAI,KAAK,IAAI,aAAa,OAAO,SAAS,CAAC,IAAI;AAC7C,WAAO,QAAQ,sCAA6B;AAE9C,QAAM,SAAS;AAAA,IACb,KAAK,OAAO,WAAW,aAAa,IAAI,KAAK,OAAO,MAAM,cAAc,MAAM,IAAI,KAAK;AAAA,EACzF;AACA,MAAI,UAAU,QAAQ,OAAO,WAAW,EAAG,QAAO,QAAQ,kCAA2B;AACrF,QAAM,MAAM,MAAM,WAAW,OAAO,OAAO;AAAA,IACzC;AAAA,IACA;AAAA,IACA,EAAE,MAAM,QAAQ,MAAM,UAAU;AAAA,IAChC;AAAA,IACA,CAAC,QAAQ;AAAA,EACX;AACA,QAAM,SAAS,IAAI,YAAY,EAAE,OAAO,GAAG,EAAE,IAAI,SAAS,IAAI,KAAK,OAAO,EAAE;AAC5E,MAAI,UAAU;AACd,aAAW,SAAS,WAAW,MAAM,GAAG,GAAG;AACzC,UAAM,QAAQ,MAAM,QAAQ,GAAG;AAC/B,QAAI,QAAQ,KAAK,MAAM,MAAM,GAAG,KAAK,MAAM,kBAAmB;AAC9D,UAAM,YAAY,YAAY,MAAM,MAAM,QAAQ,CAAC,CAAC;AAEpD,QACE,aAAa,QACZ,MAAM,WAAW,OAAO,OAAO,OAAO,QAAQ,KAAK,WAAW,MAAM,GACrE;AACA,gBAAU;AACV;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,QAAS,QAAO,QAAQ,kCAA2B;AAExD,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,KAAK,OAAO;AAAA,EAChC,QAAQ;AACN,WAAO,QAAQ,sCAA6B;AAAA,EAC9C;AACA,QAAM,WAAW,oBAAoB,UAAU,IAAI;AACnD,MAAI,CAAC,SAAS,QAAS,QAAO,QAAQ,sCAA6B;AACnE,SAAO,EAAE,IAAI,MAAM,IAAI,UAAU,SAAS,KAAK;AACjD;AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA,qBAAAC;AAAA,EACA,4BAAAC;AAAA,EACA,4BAAAC;AAAA,OAGK;",
+  "names": ["WebhookRefusal", "WEBHOOK_ID_HEADER", "WEBHOOK_SIGNATURE_HEADER", "WEBHOOK_TIMESTAMP_HEADER"]
+}