@tangle-network/agent-runtime 0.8.0 → 0.11.0

package/dist/platform.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Server-side client for the Tangle platform's cross-site SSO bridge.
+ *
+ * Consumer apps (gtm-agent, tax-agent, legal-agent, creative-agent, …)
+ * use this to:
+ *   1. Build an /authorize URL that lands the user on id.tangle.tools
+ *      and brings them back with a single-use code.
+ *   2. Exchange that code for an API key + the user's identity.
+ *
+ * The platform endpoint contract is documented in
+ * `products/platform/api/src/routes/cross-site.ts`. This client only
+ * speaks HTTP — no SDK weight, no transitive deps.
+ */
+interface PlatformAuthClientOptions {
+    /** Platform base URL, e.g. `https://id.tangle.tools`. */
+    baseUrl: string;
+    /** App id as registered in the platform's TRUSTED_APPS registry. */
+    appId: string;
+    /** Override the global fetch (useful for tests + edge runtimes). */
+    fetchImpl?: typeof fetch;
+}
+interface AuthorizeUrlOptions {
+    /** Required CSRF token; the consumer verifies it on the callback. */
+    state: string;
+    /**
+     * Final redirect URI. Must be one of the URIs registered for `appId`
+     * on the platform. Omit to use the first registered URI.
+     */
+    redirectUri?: string;
+    /** Force the login screen even if a session is already active. */
+    prompt?: 'login';
+    /** Pre-fill the email field on the login screen. */
+    email?: string;
+}
+interface ExchangeCodeResult {
+    apiKey: string;
+    user: {
+        id: string;
+        email: string;
+        name?: string;
+    };
+    plan: {
+        tier: string;
+    };
+}
+declare class PlatformAuthError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+declare class PlatformAuthClient {
+    private readonly baseUrl;
+    private readonly appId;
+    private readonly fetchImpl;
+    constructor(options: PlatformAuthClientOptions);
+    /**
+     * Build the URL the user is redirected to in order to start SSO.
+     * The platform redirects back to one of `appId`'s registered
+     * `redirectUris` with `?code=...&app=...&state=...`.
+     */
+    authorizeUrl(options: AuthorizeUrlOptions): string;
+    /**
+     * Exchange a single-use auth code (delivered to the consumer's
+     * callback by the platform) for an API key + the user's identity.
+     * Codes are single-use and expire ~5 minutes after issue.
+     */
+    exchange(code: string): Promise<ExchangeCodeResult>;
+}
+
+/**
+ * Server-side client for the Tangle platform's integrations hub
+ * (`/v1/integrations/*`). Consumer apps use this instead of rolling
+ * their own OAuth + connection tables.
+ *
+ * Auth: the caller supplies a bearer (either the user's API key from
+ * cross-site exchange, or a platform service token) on construction.
+ * Per-request override via `headers` is supported.
+ *
+ * Endpoint contract: `products/platform/api/src/routes/integrations.ts`.
+ */
+interface PlatformHubClientOptions {
+    /** Platform base URL, e.g. `https://id.tangle.tools`. */
+    baseUrl: string;
+    /** Bearer credential — user API key or service token. */
+    bearer: string;
+    /** Override fetch (tests + edge runtimes). */
+    fetchImpl?: typeof fetch;
+}
+interface PlatformConnection {
+    id: string;
+    providerId: string;
+    connectorId: string;
+    status: 'connected' | 'pending' | 'revoked' | 'expired' | string;
+    grantedScopes?: string[];
+    account?: {
+        identity?: string;
+        displayName?: string;
+    } & Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    expiresAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface PlatformCatalogProvider {
+    providerId: string;
+    displayName?: string;
+    description?: string;
+    authMode?: string;
+    connectors?: PlatformCatalogConnector[];
+    [k: string]: unknown;
+}
+interface PlatformCatalogConnector {
+    connectorId: string;
+    displayName?: string;
+    description?: string;
+    scopes?: string[];
+    [k: string]: unknown;
+}
+interface StartAuthInput {
+    providerId: string;
+    connectorId: string;
+    /** Where the platform redirects the user back to after OAuth. */
+    returnUrl: string;
+    requestedScopes?: string[];
+    state?: string;
+    metadata?: Record<string, unknown>;
+    /** Required when the bearer is a service token impersonating a user. */
+    ownerUserId?: string;
+}
+interface StartAuthResult {
+    authorizationUrl: string;
+    state: string;
+}
+interface BundleCapabilityInput {
+    manifestId?: string;
+    grantIds?: string[];
+    subject: {
+        type: 'user' | 'team' | 'app';
+        id: string;
+    };
+    ttlMs: number;
+}
+interface BundleCapabilityResult {
+    bundle: Record<string, unknown>;
+    env: Record<string, string>;
+}
+interface HealthCheck {
+    connectionId: string;
+    providerId: string;
+    connectorId: string;
+    status: 'ok' | 'degraded' | 'failing' | 'unknown' | string;
+    checks?: Record<string, unknown>;
+    checkedAt?: string;
+}
+declare class PlatformHubError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly body: unknown;
+    constructor(message: string, status: number, code: string | undefined, body: unknown);
+}
+declare class PlatformHubClient {
+    private readonly baseUrl;
+    private readonly bearer;
+    private readonly fetchImpl;
+    constructor(options: PlatformHubClientOptions);
+    /** List the integration catalog (providers + connectors). */
+    catalog(): Promise<{
+        providers: PlatformCatalogProvider[];
+    } & Record<string, unknown>>;
+    /** List the calling user's integration connections. */
+    listConnections(): Promise<PlatformConnection[]>;
+    /** Revoke (and disable) a connection by id. */
+    revokeConnection(connectionId: string): Promise<{
+        connection: PlatformConnection;
+        revokedGrants: unknown[];
+        providerRevocation: {
+            ok: boolean;
+        };
+    }>;
+    /** Begin OAuth — returns the URL to send the user to. */
+    startAuth(input: StartAuthInput): Promise<StartAuthResult>;
+    /** List connection healthchecks (last known state). */
+    listHealthchecks(): Promise<HealthCheck[]>;
+    /** Trigger a fresh healthcheck pass. */
+    runHealthchecks(): Promise<{
+        scheduled: number;
+    }>;
+    /**
+     * Mint a sandbox-injectable capability bundle (env vars + scoped
+     * capability tokens) so a sandbox can invoke integrations on the
+     * user's behalf without seeing the underlying provider tokens.
+     */
+    bundleCapabilities(input: BundleCapabilityInput): Promise<BundleCapabilityResult>;
+    private request;
+}
+
+export { type AuthorizeUrlOptions, type BundleCapabilityInput, type BundleCapabilityResult, type ExchangeCodeResult, type HealthCheck, PlatformAuthClient, type PlatformAuthClientOptions, PlatformAuthError, type PlatformCatalogConnector, type PlatformCatalogProvider, type PlatformConnection, PlatformHubClient, type PlatformHubClientOptions, PlatformHubError, type StartAuthInput, type StartAuthResult };

package/dist/platform.js

@@ -0,0 +1,187 @@
+import "./chunk-DGUM43GV.js";
+
+// src/platform/auth.ts
+var PlatformAuthError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "PlatformAuthError";
+  }
+  status;
+  body;
+};
+var PlatformAuthClient = class {
+  baseUrl;
+  appId;
+  fetchImpl;
+  constructor(options) {
+    if (!options.baseUrl) throw new Error("PlatformAuthClient: baseUrl is required");
+    if (!options.appId) throw new Error("PlatformAuthClient: appId is required");
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.appId = options.appId;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  /**
+   * Build the URL the user is redirected to in order to start SSO.
+   * The platform redirects back to one of `appId`'s registered
+   * `redirectUris` with `?code=...&app=...&state=...`.
+   */
+  authorizeUrl(options) {
+    if (!options.state) {
+      throw new Error("PlatformAuthClient.authorizeUrl: state is required for CSRF");
+    }
+    const url = new URL("/cross-site/authorize", this.baseUrl);
+    url.searchParams.set("app", this.appId);
+    url.searchParams.set("state", options.state);
+    if (options.redirectUri) url.searchParams.set("redirect", options.redirectUri);
+    if (options.prompt) url.searchParams.set("prompt", options.prompt);
+    if (options.email) url.searchParams.set("email", options.email);
+    return url.toString();
+  }
+  /**
+   * Exchange a single-use auth code (delivered to the consumer's
+   * callback by the platform) for an API key + the user's identity.
+   * Codes are single-use and expire ~5 minutes after issue.
+   */
+  async exchange(code) {
+    if (!code) throw new Error("PlatformAuthClient.exchange: code is required");
+    const res = await this.fetchImpl(`${this.baseUrl}/cross-site/exchange`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ code, app: this.appId })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      const message = body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : `Platform exchange failed (${res.status})`;
+      throw new PlatformAuthError(message, res.status, body);
+    }
+    const result = body;
+    if (!result.apiKey || !result.user?.id) {
+      throw new PlatformAuthError(
+        "Platform exchange response is missing apiKey or user",
+        res.status,
+        body
+      );
+    }
+    return result;
+  }
+};
+
+// src/platform/integrations.ts
+var PlatformHubError = class extends Error {
+  constructor(message, status, code, body) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.name = "PlatformHubError";
+  }
+  status;
+  code;
+  body;
+};
+var PlatformHubClient = class {
+  baseUrl;
+  bearer;
+  fetchImpl;
+  constructor(options) {
+    if (!options.baseUrl) throw new Error("PlatformHubClient: baseUrl is required");
+    if (!options.bearer) throw new Error("PlatformHubClient: bearer is required");
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.bearer = options.bearer;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  /** List the integration catalog (providers + connectors). */
+  catalog() {
+    return this.request("GET", "/v1/integrations/catalog");
+  }
+  /** List the calling user's integration connections. */
+  async listConnections() {
+    const data = await this.request(
+      "GET",
+      "/v1/integrations/connections"
+    );
+    return data.connections;
+  }
+  /** Revoke (and disable) a connection by id. */
+  revokeConnection(connectionId) {
+    return this.request(
+      "DELETE",
+      `/v1/integrations/connections/${encodeURIComponent(connectionId)}`
+    );
+  }
+  /** Begin OAuth — returns the URL to send the user to. */
+  startAuth(input) {
+    return this.request("POST", "/v1/integrations/auth/start", input);
+  }
+  /** List connection healthchecks (last known state). */
+  async listHealthchecks() {
+    const data = await this.request(
+      "GET",
+      "/v1/integrations/healthchecks"
+    );
+    return data.healthchecks;
+  }
+  /** Trigger a fresh healthcheck pass. */
+  runHealthchecks() {
+    return this.request("POST", "/v1/integrations/healthchecks/run", {});
+  }
+  /**
+   * Mint a sandbox-injectable capability bundle (env vars + scoped
+   * capability tokens) so a sandbox can invoke integrations on the
+   * user's behalf without seeing the underlying provider tokens.
+   */
+  bundleCapabilities(input) {
+    return this.request("POST", "/v1/integrations/capabilities/bundle", input);
+  }
+  async request(method, path, body) {
+    const headers = {
+      authorization: `Bearer ${this.bearer}`,
+      accept: "application/json"
+    };
+    if (body !== void 0) headers["content-type"] = "application/json";
+    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const text = await res.text();
+    let parsed = null;
+    if (text) {
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+      }
+    }
+    if (!res.ok || parsed && parsed.success === false) {
+      const code = parsed?.error && typeof parsed.error === "object" ? parsed.error.code : void 0;
+      const message = parsed?.error && typeof parsed.error === "object" && parsed.error.message || (typeof parsed?.error === "string" ? parsed.error : `Platform hub error (${res.status})`);
+      throw new PlatformHubError(message, res.status, code, parsed ?? text);
+    }
+    if (!parsed) {
+      throw new PlatformHubError(
+        `Platform hub returned non-JSON success (${res.status})`,
+        res.status,
+        void 0,
+        text
+      );
+    }
+    if (parsed.data === void 0) {
+      throw new PlatformHubError(
+        "Platform hub envelope missing `data`",
+        res.status,
+        void 0,
+        parsed
+      );
+    }
+    return parsed.data;
+  }
+};
+export {
+  PlatformAuthClient,
+  PlatformAuthError,
+  PlatformHubClient,
+  PlatformHubError
+};
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/platform/auth.ts","../src/platform/integrations.ts"],"sourcesContent":["/**\n * Server-side client for the Tangle platform's cross-site SSO bridge.\n *\n * Consumer apps (gtm-agent, tax-agent, legal-agent, creative-agent, …)\n * use this to:\n *   1. Build an /authorize URL that lands the user on id.tangle.tools\n *      and brings them back with a single-use code.\n *   2. Exchange that code for an API key + the user's identity.\n *\n * The platform endpoint contract is documented in\n * `products/platform/api/src/routes/cross-site.ts`. This client only\n * speaks HTTP — no SDK weight, no transitive deps.\n */\n\nexport interface PlatformAuthClientOptions {\n  /** Platform base URL, e.g. `https://id.tangle.tools`. */\n  baseUrl: string\n  /** App id as registered in the platform's TRUSTED_APPS registry. */\n  appId: string\n  /** Override the global fetch (useful for tests + edge runtimes). */\n  fetchImpl?: typeof fetch\n}\n\nexport interface AuthorizeUrlOptions {\n  /** Required CSRF token; the consumer verifies it on the callback. */\n  state: string\n  /**\n   * Final redirect URI. Must be one of the URIs registered for `appId`\n   * on the platform. Omit to use the first registered URI.\n   */\n  redirectUri?: string\n  /** Force the login screen even if a session is already active. */\n  prompt?: 'login'\n  /** Pre-fill the email field on the login screen. */\n  email?: string\n}\n\nexport interface ExchangeCodeResult {\n  apiKey: string\n  user: {\n    id: string\n    email: string\n    name?: string\n  }\n  plan: {\n    tier: string\n  }\n}\n\nexport class PlatformAuthError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly body: unknown,\n  ) {\n    super(message)\n    this.name = 'PlatformAuthError'\n  }\n}\n\nexport class PlatformAuthClient {\n  private readonly baseUrl: string\n  private readonly appId: string\n  private readonly fetchImpl: typeof fetch\n\n  constructor(options: PlatformAuthClientOptions) {\n    if (!options.baseUrl) throw new Error('PlatformAuthClient: baseUrl is required')\n    if (!options.appId) throw new Error('PlatformAuthClient: appId is required')\n    this.baseUrl = options.baseUrl.replace(/\\/+$/, '')\n    this.appId = options.appId\n    this.fetchImpl = options.fetchImpl ?? fetch\n  }\n\n  /**\n   * Build the URL the user is redirected to in order to start SSO.\n   * The platform redirects back to one of `appId`'s registered\n   * `redirectUris` with `?code=...&app=...&state=...`.\n   */\n  authorizeUrl(options: AuthorizeUrlOptions): string {\n    if (!options.state) {\n      throw new Error('PlatformAuthClient.authorizeUrl: state is required for CSRF')\n    }\n    const url = new URL('/cross-site/authorize', this.baseUrl)\n    url.searchParams.set('app', this.appId)\n    url.searchParams.set('state', options.state)\n    if (options.redirectUri) url.searchParams.set('redirect', options.redirectUri)\n    if (options.prompt) url.searchParams.set('prompt', options.prompt)\n    if (options.email) url.searchParams.set('email', options.email)\n    return url.toString()\n  }\n\n  /**\n   * Exchange a single-use auth code (delivered to the consumer's\n   * callback by the platform) for an API key + the user's identity.\n   * Codes are single-use and expire ~5 minutes after issue.\n   */\n  async exchange(code: string): Promise<ExchangeCodeResult> {\n    if (!code) throw new Error('PlatformAuthClient.exchange: code is required')\n    const res = await this.fetchImpl(`${this.baseUrl}/cross-site/exchange`, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ code, app: this.appId }),\n    })\n    const body = await res.json().catch(() => null)\n    if (!res.ok) {\n      const message =\n        body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'\n          ? body.error\n          : `Platform exchange failed (${res.status})`\n      throw new PlatformAuthError(message, res.status, body)\n    }\n    const result = body as Partial<ExchangeCodeResult>\n    if (!result.apiKey || !result.user?.id) {\n      throw new PlatformAuthError(\n        'Platform exchange response is missing apiKey or user',\n        res.status,\n        body,\n      )\n    }\n    return result as ExchangeCodeResult\n  }\n}\n","/**\n * Server-side client for the Tangle platform's integrations hub\n * (`/v1/integrations/*`). Consumer apps use this instead of rolling\n * their own OAuth + connection tables.\n *\n * Auth: the caller supplies a bearer (either the user's API key from\n * cross-site exchange, or a platform service token) on construction.\n * Per-request override via `headers` is supported.\n *\n * Endpoint contract: `products/platform/api/src/routes/integrations.ts`.\n */\n\nexport interface PlatformHubClientOptions {\n  /** Platform base URL, e.g. `https://id.tangle.tools`. */\n  baseUrl: string\n  /** Bearer credential — user API key or service token. */\n  bearer: string\n  /** Override fetch (tests + edge runtimes). */\n  fetchImpl?: typeof fetch\n}\n\nexport interface PlatformConnection {\n  id: string\n  providerId: string\n  connectorId: string\n  status: 'connected' | 'pending' | 'revoked' | 'expired' | string\n  grantedScopes?: string[]\n  account?: { identity?: string; displayName?: string } & Record<string, unknown>\n  metadata?: Record<string, unknown>\n  expiresAt?: string | null\n  createdAt?: string\n  updatedAt?: string\n}\n\nexport interface PlatformCatalogProvider {\n  providerId: string\n  displayName?: string\n  description?: string\n  authMode?: string\n  connectors?: PlatformCatalogConnector[]\n  [k: string]: unknown\n}\n\nexport interface PlatformCatalogConnector {\n  connectorId: string\n  displayName?: string\n  description?: string\n  scopes?: string[]\n  [k: string]: unknown\n}\n\nexport interface StartAuthInput {\n  providerId: string\n  connectorId: string\n  /** Where the platform redirects the user back to after OAuth. */\n  returnUrl: string\n  requestedScopes?: string[]\n  state?: string\n  metadata?: Record<string, unknown>\n  /** Required when the bearer is a service token impersonating a user. */\n  ownerUserId?: string\n}\n\nexport interface StartAuthResult {\n  authorizationUrl: string\n  state: string\n}\n\nexport interface BundleCapabilityInput {\n  manifestId?: string\n  grantIds?: string[]\n  subject: { type: 'user' | 'team' | 'app'; id: string }\n  ttlMs: number\n}\n\nexport interface BundleCapabilityResult {\n  bundle: Record<string, unknown>\n  env: Record<string, string>\n}\n\nexport interface HealthCheck {\n  connectionId: string\n  providerId: string\n  connectorId: string\n  status: 'ok' | 'degraded' | 'failing' | 'unknown' | string\n  checks?: Record<string, unknown>\n  checkedAt?: string\n}\n\nexport class PlatformHubError extends Error {\n  constructor(\n    message: string,\n    public readonly status: number,\n    public readonly code: string | undefined,\n    public readonly body: unknown,\n  ) {\n    super(message)\n    this.name = 'PlatformHubError'\n  }\n}\n\ninterface PlatformEnvelope<T> {\n  success: boolean\n  data?: T\n  error?: { code?: string; message?: string } | string\n}\n\nexport class PlatformHubClient {\n  private readonly baseUrl: string\n  private readonly bearer: string\n  private readonly fetchImpl: typeof fetch\n\n  constructor(options: PlatformHubClientOptions) {\n    if (!options.baseUrl) throw new Error('PlatformHubClient: baseUrl is required')\n    if (!options.bearer) throw new Error('PlatformHubClient: bearer is required')\n    this.baseUrl = options.baseUrl.replace(/\\/+$/, '')\n    this.bearer = options.bearer\n    this.fetchImpl = options.fetchImpl ?? fetch\n  }\n\n  /** List the integration catalog (providers + connectors). */\n  catalog(): Promise<{ providers: PlatformCatalogProvider[] } & Record<string, unknown>> {\n    return this.request('GET', '/v1/integrations/catalog')\n  }\n\n  /** List the calling user's integration connections. */\n  async listConnections(): Promise<PlatformConnection[]> {\n    const data = await this.request<{ connections: PlatformConnection[] }>(\n      'GET',\n      '/v1/integrations/connections',\n    )\n    return data.connections\n  }\n\n  /** Revoke (and disable) a connection by id. */\n  revokeConnection(connectionId: string): Promise<{\n    connection: PlatformConnection\n    revokedGrants: unknown[]\n    providerRevocation: { ok: boolean }\n  }> {\n    return this.request(\n      'DELETE',\n      `/v1/integrations/connections/${encodeURIComponent(connectionId)}`,\n    )\n  }\n\n  /** Begin OAuth — returns the URL to send the user to. */\n  startAuth(input: StartAuthInput): Promise<StartAuthResult> {\n    return this.request('POST', '/v1/integrations/auth/start', input)\n  }\n\n  /** List connection healthchecks (last known state). */\n  async listHealthchecks(): Promise<HealthCheck[]> {\n    const data = await this.request<{ healthchecks: HealthCheck[] }>(\n      'GET',\n      '/v1/integrations/healthchecks',\n    )\n    return data.healthchecks\n  }\n\n  /** Trigger a fresh healthcheck pass. */\n  runHealthchecks(): Promise<{ scheduled: number }> {\n    return this.request('POST', '/v1/integrations/healthchecks/run', {})\n  }\n\n  /**\n   * Mint a sandbox-injectable capability bundle (env vars + scoped\n   * capability tokens) so a sandbox can invoke integrations on the\n   * user's behalf without seeing the underlying provider tokens.\n   */\n  bundleCapabilities(input: BundleCapabilityInput): Promise<BundleCapabilityResult> {\n    return this.request('POST', '/v1/integrations/capabilities/bundle', input)\n  }\n\n  private async request<T>(\n    method: 'GET' | 'POST' | 'DELETE' | 'PUT',\n    path: string,\n    body?: unknown,\n  ): Promise<T> {\n    const headers: Record<string, string> = {\n      authorization: `Bearer ${this.bearer}`,\n      accept: 'application/json',\n    }\n    if (body !== undefined) headers['content-type'] = 'application/json'\n\n    const res = await this.fetchImpl(`${this.baseUrl}${path}`, {\n      method,\n      headers,\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    })\n    const text = await res.text()\n    let parsed: PlatformEnvelope<T> | null = null\n    if (text) {\n      try {\n        parsed = JSON.parse(text)\n      } catch {\n        // fall through to error handling below\n      }\n    }\n    if (!res.ok || (parsed && parsed.success === false)) {\n      const code = parsed?.error && typeof parsed.error === 'object' ? parsed.error.code : undefined\n      const message =\n        (parsed?.error && typeof parsed.error === 'object' && parsed.error.message) ||\n        (typeof parsed?.error === 'string' ? parsed.error : `Platform hub error (${res.status})`)\n      throw new PlatformHubError(message, res.status, code, parsed ?? text)\n    }\n    if (!parsed) {\n      throw new PlatformHubError(\n        `Platform hub returned non-JSON success (${res.status})`,\n        res.status,\n        undefined,\n        text,\n      )\n    }\n    if (parsed.data === undefined) {\n      throw new PlatformHubError(\n        'Platform hub envelope missing `data`',\n        res.status,\n        undefined,\n        parsed,\n      )\n    }\n    return parsed.data\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/types-D_MXrmJP.d.ts

@@ -0,0 +1,245 @@
+import { AnalystRunEvent, AnalystRunInputs, AnalystFinding, AnalystRunResult, FindingsDiff } from '@tangle-network/agent-eval';
+
+/**
+ * Public types for the closed-loop analyst orchestrator.
+ *
+ * The orchestrator is the one call agent apps reach for. It binds:
+ *   - the AnalystRegistry + a chosen set of analyst kinds
+ *   - a FindingsStore (durable JSONL ledger + cross-run diff)
+ *   - an optional KnowledgeAdapter (closes the analysis → wiki side)
+ *   - an optional ImprovementAdapter (closes the analysis → prompt /
+ *     tool / scaffolding side)
+ *
+ * Adapters keep agent-runtime decoupled from the specific storage
+ * implementation. Consumers wire agent-knowledge once at app init.
+ */
+
+/** Knowledge-side bridge — consumers wire `proposeFromFindings` from agent-knowledge. */
+interface KnowledgeAdapter<TProposal = unknown> {
+    /**
+     * Convert a findings batch into proposals. Returns the partitioned
+     * result so the loop can report (and optionally fail on) malformed
+     * findings. Implementations SHOULD honour the convention "non-
+     * knowledge subjects return null and are counted in `skipped`."
+     */
+    proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): Promise<KnowledgeProposalBatch<TProposal>> | KnowledgeProposalBatch<TProposal>;
+    /**
+     * Optional auto-apply. The loop calls this only when
+     * `autoApply.knowledge` is true AND the proposal's source-finding
+     * confidence ≥ `autoApply.knowledgeConfidenceThreshold`. Anything
+     * below the threshold is returned in the report but never written.
+     */
+    apply?(proposals: ReadonlyArray<TProposal>): Promise<{
+        written: string[];
+        warnings: string[];
+    }>;
+}
+interface KnowledgeProposalBatch<TProposal = unknown> {
+    proposals: TProposal[];
+    skipped: number;
+    errors: Array<{
+        findingId: string;
+        subject: string;
+        message: string;
+    }>;
+}
+/** Improvement-side bridge — proposes / applies prompt + tool + scaffolding edits. */
+interface ImprovementAdapter<TEdit = unknown> {
+    proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): Promise<ImprovementEditBatch<TEdit>> | ImprovementEditBatch<TEdit>;
+    apply?(edits: ReadonlyArray<TEdit>): Promise<{
+        applied: string[];
+        warnings: string[];
+    }>;
+}
+interface ImprovementEditBatch<TEdit = unknown> {
+    edits: TEdit[];
+    skipped: number;
+    errors: Array<{
+        findingId: string;
+        subject: string;
+        message: string;
+    }>;
+}
+/** Tunable safety rails for auto-apply. */
+interface AutoApplyPolicy {
+    /** When true AND `knowledgeAdapter.apply` exists, write knowledge proposals. */
+    knowledge?: boolean;
+    /** Minimum source-finding confidence required to auto-apply a knowledge proposal. */
+    knowledgeConfidenceThreshold?: number;
+    /** When true AND `improvementAdapter.apply` exists, apply improvement edits. */
+    improvement?: boolean;
+    /** Minimum source-finding confidence required to auto-apply an improvement edit. */
+    improvementConfidenceThreshold?: number;
+}
+interface RunAnalystLoopOpts {
+    /** The run id of the work being analysed. */
+    runId: string;
+    /** The registry — pre-populated with the analyst kinds the consumer wants. */
+    registry: AnalystRegistryLike;
+    /** Inputs forwarded to `registry.run` — typically `{ traceStore }`. */
+    inputs: AnalystRunInputs;
+    /**
+     * Findings ledger. The loop appends the new run + diffs against the
+     * baseline run before running adapters. Pass `null` to skip
+     * persistence (useful for one-shot analyses).
+     */
+    findingsStore: FindingsStoreLike | null;
+    /**
+     * Prior run id whose findings the loop reads + provides to analysts
+     * as `priorFindings` AND diffs against. When omitted, the loop picks
+     * the most recent run in the store (excluding `runId` itself); pass
+     * `null` to explicitly start with an empty baseline.
+     */
+    baselineRunId?: string | null;
+    /** Strategy for forwarding prior findings into `ctx.priorFindings`. */
+    priorFindingsStrategy?: 'per-kind' | 'wildcard' | 'none';
+    /** Knowledge-side bridge — usually `agent-knowledge`'s `proposeFromFindings`. */
+    knowledgeAdapter?: KnowledgeAdapter;
+    /** Improvement-side bridge — usually a consumer-specific prompt/tool diff producer. */
+    improvementAdapter?: ImprovementAdapter;
+    /** Auto-apply rails. Default off; review-then-apply is the safer default. */
+    autoApply?: AutoApplyPolicy;
+    /** Optional logger. Defaults to `console.log` for `[analyst-loop]` lines. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /**
+     * Event sink for live progress. Called for every phase of the loop:
+     * baseline resolution, registry events forwarded from `runStream`,
+     * ledger persistence, diff, knowledge / improvement proposals +
+     * apply outcomes, and the terminal `loop-completed`. Awaited so
+     * slow sinks (SSE write, JSONL append) apply backpressure.
+     *
+     * The callback MUST NOT throw — exceptions propagate and abort the
+     * loop. Catch + swallow internally if your sink is unreliable.
+     */
+    onEvent?: (event: AnalystLoopEvent) => void | Promise<void>;
+}
+interface RunAnalystLoopResult<TProposal = unknown, TEdit = unknown> {
+    runId: string;
+    baselineRunId: string | null;
+    analystResult: AnalystRunResult;
+    diff: FindingsDiff | null;
+    knowledge: KnowledgeReport<TProposal> | null;
+    improvement: ImprovementReport<TEdit> | null;
+}
+interface KnowledgeReport<TProposal = unknown> {
+    proposals: TProposal[];
+    applied: string[];
+    skipped: number;
+    errors: Array<{
+        findingId: string;
+        subject: string;
+        message: string;
+    }>;
+    withheld_for_review: number;
+}
+interface ImprovementReport<TEdit = unknown> {
+    edits: TEdit[];
+    applied: string[];
+    skipped: number;
+    errors: Array<{
+        findingId: string;
+        subject: string;
+        message: string;
+    }>;
+    withheld_for_review: number;
+}
+/**
+ * Narrowed shape we accept for `AnalystRegistry` so the orchestrator
+ * remains testable without instantiating the real class. The real
+ * class satisfies this trivially.
+ */
+interface AnalystRegistryLike {
+    list(): ReadonlyArray<{
+        id: string;
+    }>;
+    run(runId: string, inputs: AnalystRunInputs, opts?: {
+        priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+        [k: string]: unknown;
+    }): Promise<AnalystRunResult>;
+}
+/** Narrowed shape we accept for `FindingsStore`. */
+interface FindingsStoreLike {
+    loadAll(): ReadonlyArray<AnalystFinding & {
+        run_id: string;
+    }>;
+    loadRun(runId: string): ReadonlyArray<AnalystFinding & {
+        run_id: string;
+    }>;
+    append(runId: string, findings: ReadonlyArray<AnalystFinding>): Promise<void>;
+}
+
+/**
+ * Narrow the `AnalystRegistryLike` further when we need streaming: the
+ * loop checks if the registry exposes `runStream` and uses it when
+ * present, falling back to `run()` otherwise. This keeps the type
+ * surface backwards-compatible — older registry shims that only
+ * implement `run` still work; they just don't forward per-analyst
+ * events.
+ */
+interface AnalystRegistryStreamingLike extends AnalystRegistryLike {
+    runStream?(runId: string, inputs: AnalystRunInputs, opts?: {
+        priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+        [k: string]: unknown;
+    }): AsyncIterable<AnalystRunEvent>;
+}
+/**
+ * Events emitted by `runAnalystLoop` via `opts.onEvent`. UIs and
+ * JSONL tail-sinks consume this stream. The loop awaits each
+ * callback so a slow sink applies backpressure to the loop's phases
+ * (e.g. an SSE write that takes 200ms delays the next phase by
+ * 200ms — the loop never out-paces its observer).
+ *
+ * Forwards registry events verbatim via `analyst` so consumers don't
+ * have to wire two streams.
+ */
+type AnalystLoopEvent = {
+    type: 'baseline-resolved';
+    runId: string;
+    baselineRunId: string | null;
+    priorFindingCount: number;
+} | {
+    type: 'analyst';
+    runId: string;
+    /** Forwarded verbatim from `AnalystRegistry.runStream`. */
+    event: AnalystRunEvent;
+} | {
+    type: 'findings-persisted';
+    runId: string;
+    count: number;
+} | {
+    type: 'diff-computed';
+    runId: string;
+    baselineRunId: string;
+    appeared: number;
+    disappeared: number;
+    persisted: number;
+    changed: number;
+} | {
+    type: 'knowledge-proposed';
+    runId: string;
+    proposalCount: number;
+    skipped: number;
+    errors: number;
+} | {
+    type: 'knowledge-applied';
+    runId: string;
+    writtenCount: number;
+    withheldForReview: number;
+} | {
+    type: 'improvement-proposed';
+    runId: string;
+    editCount: number;
+    skipped: number;
+    errors: number;
+} | {
+    type: 'improvement-applied';
+    runId: string;
+    appliedCount: number;
+    withheldForReview: number;
+} | {
+    type: 'loop-completed';
+    runId: string;
+    durationMs: number;
+};
+
+export type { AnalystLoopEvent as A, FindingsStoreLike as F, ImprovementAdapter as I, KnowledgeAdapter as K, RunAnalystLoopOpts as R, RunAnalystLoopResult as a, AnalystRegistryLike as b, AnalystRegistryStreamingLike as c, AutoApplyPolicy as d, ImprovementEditBatch as e, ImprovementReport as f, KnowledgeProposalBatch as g, KnowledgeReport as h };