@tangle-network/agent-runtime 0.70.0 → 0.70.1

package/dist/platform.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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 integration hub
+ * (`/v1/hub/*`). 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.
+ *
+ * Endpoint contract (authoritative): the platform's `src/lib/hub-contract.ts`
+ * + `src/routes/hub.ts`. The platform wraps every response in
+ * `{ success, data }`; non-2xx or `success:false` surfaces as `PlatformHubError`
+ * carrying the real upstream status.
+ */
+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;
+}
+/** A live integration connection, as returned by `/v1/hub/connections`. */
+interface PlatformConnection {
+    id: string;
+    providerId: string;
+    displayName: string;
+    accountDisplay: string | null;
+    scopes: string[];
+    status: 'active' | 'revoked' | 'unhealthy' | 'reconnect_required' | (string & {});
+    health: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {});
+    createdAt: string;
+    updatedAt: string;
+    lastUsedAt: string | null;
+}
+/** A connectable provider in the catalog (`/v1/hub/providers`). */
+interface PlatformCatalogProvider {
+    providerId: string;
+    title?: string;
+    authKind?: string;
+    category?: string;
+    scopes?: string[];
+    capabilityCount?: number;
+    native?: boolean;
+    /** Whether the OAuth app's credentials are wired — the UI offers Connect
+     *  only when true. */
+    configured?: boolean;
+    [k: string]: unknown;
+}
+interface CatalogResult {
+    providers: PlatformCatalogProvider[];
+    /** Count of substrate-bundled connectors behind the catalog. */
+    substrateBundled?: number;
+    [k: string]: unknown;
+}
+interface StartAuthInput {
+    /** The provider to connect (goes in the URL path). */
+    providerId: string;
+    /** Accepted for interface compatibility; the platform's start endpoint is
+     *  provider-level and does not consume a connector id. */
+    connectorId?: string;
+    /** Where the platform redirects the user back to after OAuth. */
+    returnUrl: string;
+    /** Accepted for interface compatibility; not consumed by the start endpoint. */
+    requestedScopes?: string[];
+    /** CLI flow flag — affects the platform's post-auth redirect handling. */
+    cli?: boolean;
+}
+interface StartAuthResult {
+    /** The URL to send the user to. Normalized across the platform's two start
+     *  branches: github returns `authorizationUrl`, substrate returns
+     *  `redirectUrl`. */
+    authorizationUrl: string;
+    state: string;
+    expiresAt?: string;
+    scopes?: string[];
+}
+interface ConnectionHealth {
+    status: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {});
+    checkedAt: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface ConnectionHealthResult {
+    connection: PlatformConnection;
+    health: ConnectionHealth;
+}
+/** Last-known health for a connection, derived from the connection row. */
+interface HealthCheck {
+    connectionId: string;
+    providerId: string;
+    /** Mirrors `PlatformConnection.health`. */
+    status: ConnectionHealth['status'];
+    checkedAt?: string;
+}
+interface MintTokenInput {
+    /** The hub action the token authorizes (e.g. `slack.chat.postMessage`). */
+    actionPath: string;
+    /** Bind to a specific connection, or … */
+    connectionId?: string;
+    /** … resolve the connection by provider for the calling user. */
+    provider?: string;
+}
+interface MintTokenResult {
+    tokenId: string;
+    token: string;
+    expiresAt: string;
+}
+interface ExecInput {
+    /** The hub action path to execute. */
+    path: string;
+    input?: unknown;
+    connectionId?: string;
+}
+interface PlatformHubStatus {
+    contract?: unknown;
+    principal: {
+        kind: string;
+        userId: string;
+        [k: string]: unknown;
+    };
+    connections: {
+        connectedProviderCount: number;
+        unhealthyProviderCount: number;
+    };
+}
+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);
+    /** GET /v1/hub/providers — the connectable provider catalog. */
+    catalog(): Promise<CatalogResult>;
+    /** GET /v1/hub/connections — the calling user's live connections. */
+    listConnections(): Promise<PlatformConnection[]>;
+    /** DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. */
+    revokeConnection(connectionId: string): Promise<{
+        connection: PlatformConnection;
+    }>;
+    /**
+     * POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider
+     * is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's
+     * two start branches name the URL field differently (github → `authorizationUrl`,
+     * substrate → `redirectUrl`); this normalizes to `authorizationUrl`.
+     */
+    startAuth(input: StartAuthInput): Promise<StartAuthResult>;
+    /**
+     * Last-known health for every connection. The platform has no global
+     * healthcheck listing — health rides on each connection row — so this derives
+     * the list from `listConnections()` (one request, no extra round-trips).
+     */
+    listHealthchecks(): Promise<HealthCheck[]>;
+    /**
+     * POST /v1/hub/connections/:connectionId/health — trigger a fresh health
+     * probe for one connection and return its updated state.
+     */
+    checkConnectionHealth(connectionId: string): Promise<ConnectionHealthResult>;
+    /**
+     * Trigger a fresh health probe across all of the user's connections. The
+     * platform exposes health per-connection only, so this fans out over
+     * `listConnections()`. `scheduled` is the number of probes dispatched.
+     */
+    runHealthchecks(): Promise<{
+        scheduled: number;
+    }>;
+    /** GET /v1/hub/status — principal + aggregate connection counts. */
+    status(): Promise<PlatformHubStatus>;
+    /**
+     * POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a
+     * sandbox can use to invoke one hub action on the user's behalf without
+     * seeing the underlying provider credential.
+     */
+    mintToken(input: MintTokenInput): Promise<MintTokenResult>;
+    /** POST /v1/hub/exec — execute a hub action and return its result. */
+    exec(input: ExecInput): Promise<unknown>;
+    private request;
+}
+
+export { type AuthorizeUrlOptions, type CatalogResult, type ConnectionHealth, type ConnectionHealthResult, type ExchangeCodeResult, type ExecInput, type HealthCheck, type MintTokenInput, type MintTokenResult, PlatformAuthClient, type PlatformAuthClientOptions, PlatformAuthError, type PlatformCatalogProvider, type PlatformConnection, PlatformHubClient, type PlatformHubClientOptions, PlatformHubError, type PlatformHubStatus, type StartAuthInput, type StartAuthResult };

package/dist/platform.js

@@ -0,0 +1,229 @@
+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 ?? ((url, init) => fetch(url, init));
+  }
+  /**
+   * 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 ?? ((url, init) => fetch(url, init));
+  }
+  /** GET /v1/hub/providers — the connectable provider catalog. */
+  catalog() {
+    return this.request("GET", "/v1/hub/providers");
+  }
+  /** GET /v1/hub/connections — the calling user's live connections. */
+  async listConnections() {
+    const data = await this.request(
+      "GET",
+      "/v1/hub/connections"
+    );
+    return data.connections;
+  }
+  /** DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. */
+  revokeConnection(connectionId) {
+    return this.request("DELETE", `/v1/hub/connections/${encodeURIComponent(connectionId)}`);
+  }
+  /**
+   * POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider
+   * is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's
+   * two start branches name the URL field differently (github → `authorizationUrl`,
+   * substrate → `redirectUrl`); this normalizes to `authorizationUrl`.
+   */
+  async startAuth(input) {
+    const body = { returnUrl: input.returnUrl };
+    if (input.cli !== void 0) body.cli = input.cli;
+    const data = await this.request("POST", `/v1/hub/connections/${encodeURIComponent(input.providerId)}/start`, body);
+    const authorizationUrl = data.authorizationUrl ?? data.redirectUrl;
+    if (!authorizationUrl) {
+      throw new PlatformHubError(
+        "Platform hub start response missing an authorization URL",
+        502,
+        "HUB_INVALID_START_RESPONSE",
+        data
+      );
+    }
+    return { authorizationUrl, state: data.state, expiresAt: data.expiresAt, scopes: data.scopes };
+  }
+  /**
+   * Last-known health for every connection. The platform has no global
+   * healthcheck listing — health rides on each connection row — so this derives
+   * the list from `listConnections()` (one request, no extra round-trips).
+   */
+  async listHealthchecks() {
+    const connections = await this.listConnections();
+    return connections.map((c) => ({
+      connectionId: c.id,
+      providerId: c.providerId,
+      status: c.health,
+      checkedAt: c.updatedAt
+    }));
+  }
+  /**
+   * POST /v1/hub/connections/:connectionId/health — trigger a fresh health
+   * probe for one connection and return its updated state.
+   */
+  checkConnectionHealth(connectionId) {
+    return this.request("POST", `/v1/hub/connections/${encodeURIComponent(connectionId)}/health`);
+  }
+  /**
+   * Trigger a fresh health probe across all of the user's connections. The
+   * platform exposes health per-connection only, so this fans out over
+   * `listConnections()`. `scheduled` is the number of probes dispatched.
+   */
+  async runHealthchecks() {
+    const connections = await this.listConnections();
+    await Promise.allSettled(connections.map((c) => this.checkConnectionHealth(c.id)));
+    return { scheduled: connections.length };
+  }
+  /** GET /v1/hub/status — principal + aggregate connection counts. */
+  status() {
+    return this.request("GET", "/v1/hub/status");
+  }
+  /**
+   * POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a
+   * sandbox can use to invoke one hub action on the user's behalf without
+   * seeing the underlying provider credential.
+   */
+  mintToken(input) {
+    return this.request("POST", "/v1/hub/tokens", input);
+  }
+  /** POST /v1/hub/exec — execute a hub action and return its result. */
+  async exec(input) {
+    const data = await this.request("POST", "/v1/hub/exec", input);
+    return data.result;
+  }
+  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 =\n      options.fetchImpl ??\n      ((url: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => fetch(url, init))\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 integration hub\n * (`/v1/hub/*`). Consumer apps use this instead of rolling their own\n * 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 *\n * Endpoint contract (authoritative): the platform's `src/lib/hub-contract.ts`\n * + `src/routes/hub.ts`. The platform wraps every response in\n * `{ success, data }`; non-2xx or `success:false` surfaces as `PlatformHubError`\n * carrying the real upstream status.\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\n/** A live integration connection, as returned by `/v1/hub/connections`. */\nexport interface PlatformConnection {\n  id: string\n  providerId: string\n  displayName: string\n  accountDisplay: string | null\n  scopes: string[]\n  status: 'active' | 'revoked' | 'unhealthy' | 'reconnect_required' | (string & {})\n  health: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {})\n  createdAt: string\n  updatedAt: string\n  lastUsedAt: string | null\n}\n\n/** A connectable provider in the catalog (`/v1/hub/providers`). */\nexport interface PlatformCatalogProvider {\n  providerId: string\n  title?: string\n  authKind?: string\n  category?: string\n  scopes?: string[]\n  capabilityCount?: number\n  native?: boolean\n  /** Whether the OAuth app's credentials are wired — the UI offers Connect\n   *  only when true. */\n  configured?: boolean\n  [k: string]: unknown\n}\n\nexport interface CatalogResult {\n  providers: PlatformCatalogProvider[]\n  /** Count of substrate-bundled connectors behind the catalog. */\n  substrateBundled?: number\n  [k: string]: unknown\n}\n\nexport interface StartAuthInput {\n  /** The provider to connect (goes in the URL path). */\n  providerId: string\n  /** Accepted for interface compatibility; the platform's start endpoint is\n   *  provider-level and does not consume a connector id. */\n  connectorId?: string\n  /** Where the platform redirects the user back to after OAuth. */\n  returnUrl: string\n  /** Accepted for interface compatibility; not consumed by the start endpoint. */\n  requestedScopes?: string[]\n  /** CLI flow flag — affects the platform's post-auth redirect handling. */\n  cli?: boolean\n}\n\nexport interface StartAuthResult {\n  /** The URL to send the user to. Normalized across the platform's two start\n   *  branches: github returns `authorizationUrl`, substrate returns\n   *  `redirectUrl`. */\n  authorizationUrl: string\n  state: string\n  expiresAt?: string\n  scopes?: string[]\n}\n\nexport interface ConnectionHealth {\n  status: 'unknown' | 'healthy' | 'unhealthy' | 'rate_limited' | (string & {})\n  checkedAt: string\n  error?: { code: string; message: string }\n}\n\nexport interface ConnectionHealthResult {\n  connection: PlatformConnection\n  health: ConnectionHealth\n}\n\n/** Last-known health for a connection, derived from the connection row. */\nexport interface HealthCheck {\n  connectionId: string\n  providerId: string\n  /** Mirrors `PlatformConnection.health`. */\n  status: ConnectionHealth['status']\n  checkedAt?: string\n}\n\nexport interface MintTokenInput {\n  /** The hub action the token authorizes (e.g. `slack.chat.postMessage`). */\n  actionPath: string\n  /** Bind to a specific connection, or … */\n  connectionId?: string\n  /** … resolve the connection by provider for the calling user. */\n  provider?: string\n}\n\nexport interface MintTokenResult {\n  tokenId: string\n  token: string\n  expiresAt: string\n}\n\nexport interface ExecInput {\n  /** The hub action path to execute. */\n  path: string\n  input?: unknown\n  connectionId?: string\n}\n\nexport interface PlatformHubStatus {\n  contract?: unknown\n  principal: { kind: string; userId: string; [k: string]: unknown }\n  connections: { connectedProviderCount: number; unhealthyProviderCount: number }\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 =\n      options.fetchImpl ??\n      ((url: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => fetch(url, init))\n  }\n\n  /** GET /v1/hub/providers — the connectable provider catalog. */\n  catalog(): Promise<CatalogResult> {\n    return this.request('GET', '/v1/hub/providers')\n  }\n\n  /** GET /v1/hub/connections — the calling user's live connections. */\n  async listConnections(): Promise<PlatformConnection[]> {\n    const data = await this.request<{ connections: PlatformConnection[] }>(\n      'GET',\n      '/v1/hub/connections',\n    )\n    return data.connections\n  }\n\n  /** DELETE /v1/hub/connections/:connectionId — revoke + disable a connection. */\n  revokeConnection(connectionId: string): Promise<{ connection: PlatformConnection }> {\n    return this.request('DELETE', `/v1/hub/connections/${encodeURIComponent(connectionId)}`)\n  }\n\n  /**\n   * POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider\n   * is taken from the URL; the body carries `returnUrl` (+ `cli`). The platform's\n   * two start branches name the URL field differently (github → `authorizationUrl`,\n   * substrate → `redirectUrl`); this normalizes to `authorizationUrl`.\n   */\n  async startAuth(input: StartAuthInput): Promise<StartAuthResult> {\n    const body: { returnUrl: string; cli?: boolean } = { returnUrl: input.returnUrl }\n    if (input.cli !== undefined) body.cli = input.cli\n    const data = await this.request<{\n      authorizationUrl?: string\n      redirectUrl?: string\n      state: string\n      expiresAt?: string\n      scopes?: string[]\n    }>('POST', `/v1/hub/connections/${encodeURIComponent(input.providerId)}/start`, body)\n    const authorizationUrl = data.authorizationUrl ?? data.redirectUrl\n    if (!authorizationUrl) {\n      throw new PlatformHubError(\n        'Platform hub start response missing an authorization URL',\n        502,\n        'HUB_INVALID_START_RESPONSE',\n        data,\n      )\n    }\n    return { authorizationUrl, state: data.state, expiresAt: data.expiresAt, scopes: data.scopes }\n  }\n\n  /**\n   * Last-known health for every connection. The platform has no global\n   * healthcheck listing — health rides on each connection row — so this derives\n   * the list from `listConnections()` (one request, no extra round-trips).\n   */\n  async listHealthchecks(): Promise<HealthCheck[]> {\n    const connections = await this.listConnections()\n    return connections.map((c) => ({\n      connectionId: c.id,\n      providerId: c.providerId,\n      status: c.health,\n      checkedAt: c.updatedAt,\n    }))\n  }\n\n  /**\n   * POST /v1/hub/connections/:connectionId/health — trigger a fresh health\n   * probe for one connection and return its updated state.\n   */\n  checkConnectionHealth(connectionId: string): Promise<ConnectionHealthResult> {\n    return this.request('POST', `/v1/hub/connections/${encodeURIComponent(connectionId)}/health`)\n  }\n\n  /**\n   * Trigger a fresh health probe across all of the user's connections. The\n   * platform exposes health per-connection only, so this fans out over\n   * `listConnections()`. `scheduled` is the number of probes dispatched.\n   */\n  async runHealthchecks(): Promise<{ scheduled: number }> {\n    const connections = await this.listConnections()\n    await Promise.allSettled(connections.map((c) => this.checkConnectionHealth(c.id)))\n    return { scheduled: connections.length }\n  }\n\n  /** GET /v1/hub/status — principal + aggregate connection counts. */\n  status(): Promise<PlatformHubStatus> {\n    return this.request('GET', '/v1/hub/status')\n  }\n\n  /**\n   * POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a\n   * sandbox can use to invoke one hub action on the user's behalf without\n   * seeing the underlying provider credential.\n   */\n  mintToken(input: MintTokenInput): Promise<MintTokenResult> {\n    return this.request('POST', '/v1/hub/tokens', input)\n  }\n\n  /** POST /v1/hub/exec — execute a hub action and return its result. */\n  async exec(input: ExecInput): Promise<unknown> {\n    const data = await this.request<{ result: unknown }>('POST', '/v1/hub/exec', input)\n    return data.result\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-DJu6TBGp.d.ts → types-BC3bZpH0.d.ts}

@@ -168,6 +168,20 @@ interface FindingsStoreLike {
     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
@@ -228,4 +242,4 @@ type AnalystLoopEvent = {
     durationMs: number;
 };
 
-export type { AnalystRegistryLike as A, ImprovementAdapter as I, KnowledgeAdapter as K, RunAnalystLoopOpts as R, RunAnalystLoopResult as a };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.70.0",
+  "version": "0.70.1",
   "description": "Shared task-lifecycle skeleton for agents: a recursive loop kernel for chat turns, one-shot tasks, and multi-attempt loops, with trace capture and eval-gated self-improvement. Domain behavior lives in adapters; scoring and ship-gates in @tangle-network/agent-eval.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -34,11 +34,21 @@
       "import": "./dist/loops.js",
       "default": "./dist/loops.js"
     },
+    "./analyst-loop": {
+      "types": "./dist/analyst-loop.d.ts",
+      "import": "./dist/analyst-loop.js",
+      "default": "./dist/analyst-loop.js"
+    },
     "./profiles": {
       "types": "./dist/profiles.d.ts",
       "import": "./dist/profiles.js",
       "default": "./dist/profiles.js"
     },
+    "./platform": {
+      "types": "./dist/platform.d.ts",
+      "import": "./dist/platform.js",
+      "default": "./dist/platform.js"
+    },
     "./mcp": {
       "types": "./dist/mcp/index.d.ts",
       "import": "./dist/mcp/index.js",