@tangle-network/agent-runtime 0.7.0 → 0.9.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,185 @@
+// 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-runtime",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Reusable runtime lifecycle for domain-specific agents.",
   "homepage": "https://github.com/tangle-network/agent-runtime#readme",
   "repository": {
@@ -18,12 +18,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./platform": {
+      "types": "./dist/platform.d.ts",
+      "import": "./dist/platform.js",
+      "default": "./dist/platform.js"
     }
   },
   "files": [
     "dist",
-    "README.md",
-    "docs"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -33,6 +37,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.0",
+    "@tangle-network/sandbox": "0.1.2",
     "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "typescript": "^5.7.0",
@@ -42,6 +47,9 @@
     "node": ">=20"
   },
   "license": "MIT",
+  "peerDependencies": {
+    "@tangle-network/sandbox": "0.1.2"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/docs/domain-agent-runtime-integration-issues.md

@@ -1,165 +0,0 @@
-# Domain Agent Runtime Integration Issues
-
-GitHub issue creation was blocked in this environment: the GitHub connector returns 404 for the private repos and `gh` is not authenticated. These are the issue drafts to open once repository credentials are available.
-
-## tax-agent
-
-Title: Integrate tax evals with agent-runtime knowledge readiness
-
-`@tangle-network/agent-runtime@0.2.0` provides the shared task harness for domain agents: `runAgentTask`, typed runtime events, `KnowledgeRequirement`, readiness scoring, question/acquisition preflight hooks, and integration with `@tangle-network/agent-eval@0.20.0`.
-
-First local implementation:
-
-- Bump root `@tangle-network/agent-eval` to `0.20.0`.
-- Add root `@tangle-network/agent-runtime` `^0.2.0`.
-- Bump `server` `@tangle-network/agent-eval` to `0.20.0`.
-- Add `tests/eval/lib/agent-runtime.ts` with `buildTaxKnowledgeRequirements()` and `runTaxAgentTask()`.
-- Add `tests/eval/lib/agent-runtime.test.ts` covering missing-context blocking and ready-context execution.
-
-Remaining changes:
-
-- Wire the runtime helper into `tests/eval/lib/deterministic-tax-workflow-runner.ts`, `tests/eval/harness/run-product-eval.ts`, `tests/eval/harness/run-workspace-eval.ts`, `tests/eval/optimize.ts`, `tests/eval/lib/agent-eval-runtime.ts`, and `tests/eval/lib/trace-sync.ts`.
-- Canonicalize tax requirements for taxpayer facts, filing year, jurisdiction, source documents, workflow tools, entity classification, elections, accounting method, book/tax reconciliation, payroll, withholding, estimated payments, credits, nexus, apportionment, OCR confidence, current authority, and user-confirmed assumptions.
-- Persist runtime events into traces: `task_start`, `readiness_start/end`, `questions_start/end`, `acquisition_start/end`, `control_start/end`, and `task_end`.
-- Report readiness score, blocking gaps, acquisition mode, evidence IDs, blocked-before-execution status, and optimizer responsible surface.
-- Classify missing documents, missing jurisdiction, stale authority, bad retrieval, insufficient evidence, contradictory evidence, missing credentials, and ambiguous taxpayer intent as knowledge failures rather than prompt failures.
-- Feed gaps into multi-shot optimization as `knowledge-requirements`, `data-acquisition`, `retrieval-policy`, or `user-question-policy`.
-- Add tests for missing taxpayer facts, missing documents, missing jurisdiction, stale authority, and fully ready execution.
-
-## legal-agent
-
-Title: Integrate legal evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` dev dependency to `^0.20.0`.
-- Add `@tangle-network/agent-runtime` dev dependency `^0.2.0`.
-- Add `tests/eval/lib/agent-runtime.ts` with `buildLegalKnowledgeRequirements()` and `runLegalAgentTask()`.
-- Add `tests/eval/lib/agent-runtime.test.ts` covering missing matter context and ready execution.
-
-Remaining changes:
-
-- Wire `runLegalAgentTask()` into `tests/eval/harness/run-product-eval.ts`, `tests/eval/harness/run-dual-agent-eval.ts`, `tests/eval/optimize.ts`, `tests/eval/lib/agent-eval-runtime.ts`, and `tests/eval/lib/trace-sync.ts`.
-- Canonicalize legal requirements for matter facts, parties, dates, jurisdiction, forum, venue, governing law, current authority, uploaded matter documents, knowledge-base search, client credentials, regulated industry constraints, deadlines, and user-approved assumptions.
-- Enforce knowledge-base retrieval before drafting or review, with retrieval evidence saved into the runtime bundle.
-- Persist runtime readiness metadata and events into trace sync and eval reports.
-- Classify missing facts, missing authority, stale law, bad retrieval, insufficient evidence, contradictory authority, missing credentials, and ambiguous user intent as knowledge failures.
-- Extend optimization ASI rows so legal reports recommend data acquisition or authority refresh before prompt rewrites.
-- Add tests for missing jurisdiction, stale authority, missing knowledge-base results, contradictory authority, and ready document review.
-
-## gtm-agent
-
-Title: Integrate GTM evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` to `0.20.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-- Add `eval/agent-runtime.ts` with `buildGtmKnowledgeRequirements()` and `runGtmAgentTask()`.
-- Add `tests/agent-runtime.test.ts` covering missing company/connector context and ready execution.
-
-Remaining changes:
-
-- Wire `runGtmAgentTask()` into `eval/business-owner/live-flow.ts`, `eval/discover-brief/run.ts`, `eval/run.ts`, `eval/agent-eval-traces.ts`, and optimizer flows.
-- Canonicalize GTM requirements for company profile, product/offer, ICP/personas, channel history, CRM state, campaign history, analytics, performance metrics, positioning, competitors, integrations, credentials, and workspace vault knowledge.
-- Turn `knowledge/wiki/company.md`, `products.md`, `channels.md`, and `open-questions.md` into runtime evidence inputs.
-- Persist readiness events into existing trace helpers and reports.
-- Classify missing company data, missing market data, stale metrics, missing credentials, bad connector retrieval, insufficient evidence, contradictory positioning, and ambiguous business-owner intent as knowledge failures.
-- Feed knowledge gaps into optimization as data-acquisition/retrieval-policy/user-question-policy issues.
-- Add tests for missing ICP, missing product context, missing connectors, stale metrics, and ready discover-brief execution.
-
-## creative-agent
-
-Title: Integrate creative evals with agent-runtime knowledge readiness
-
-First local implementation:
-
-- Bump `@tangle-network/agent-eval` to `^0.20.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-- Add `eval/control/agent-runtime.ts` with `buildCreativeKnowledgeRequirements()` and `runCreativeAgentTask()`.
-- Add `tests/agent-runtime.test.ts` covering missing creative intent/rights and ready execution.
-
-Remaining changes:
-
-- Wire `runCreativeAgentTask()` into `eval/control/creative-onboarding.ts`, `eval/control/creative-workflow-optimization.ts`, `eval/control/creative-multishot-optimization.ts`, `eval/e2e/creative-product-harness.ts`, and trace/report code.
-- Canonicalize creative requirements for intent, audience, taste thesis, references, dislikes, brand system, source rights, generated asset policy, deliverable specs, channel constraints, localization, approval policy, feedback source, and revision budget.
-- Convert onboarding answers and approval feedback into runtime evidence and reusable knowledge requirements.
-- Persist readiness events in control/e2e traces and reports.
-- Classify missing creative intent, missing taste signal, missing brand assets, missing rights, stale source policy, bad asset retrieval, insufficient evidence, contradictory feedback, and ambiguous user intent as knowledge failures.
-- Feed approval/readiness gaps into multi-shot optimization as data or policy surfaces before prompt changes.
-- Add tests for missing intent, missing rights, missing approval policy, contradictory feedback, and ready workflow execution.
-
-## blueprint-agent
-
-Title: Integrate Blueprint benchmarks with agent-runtime knowledge readiness
-
-No implementation was requested for this pass. The repo should adopt the runtime boundary before deeper report polish so benchmark failures separate missing task-world knowledge from coding-agent failures.
-
-Remaining changes:
-
-- Add `@tangle-network/agent-runtime` to the workspace package(s) that own benchmark execution.
-- Keep existing benchmark database/report terms stable if they still say `vertical`; map to runtime `domain` metadata instead of forcing a broad rename.
-- Define Blueprint requirements for task brief, repo/source checkout, package manager, framework/language, build command, test command, sandbox availability, runtime environment, credentials/secrets, Tangle Blueprint SDK docs, template/plugin docs, deploy target, and benchmark scoring contract.
-- Wrap the benchmark product path with `runAgentTask` so readiness is scored before agent execution.
-- Persist runtime events into agent-eval traces and `bench-report`.
-- Add readiness sections to markdown/HTML/JSON reports: requirement table, missing evidence, acquisition plan, blocked-before-execution runs, and readiness deltas by run/version.
-- Map failures to `knowledge_readiness_blocked`, `missing_codebase_context`, `missing_runtime_context`, `missing_credentials`, `stale_external_data`, `bad_retrieval`, `insufficient_evidence`, `contradictory_evidence`, `reasoning_error`, `tool_selection_error`, `sandbox_failure`, and `budget_exceeded`.
-- Extend holdout/promotion gates so a prompt/topology change is not promoted when observed gain is actually due to different context acquisition.
-- Add tests for missing build command, missing SDK docs, missing sandbox, stale template docs, and fully ready benchmark execution.
-
-## agent-builder
-
-Title: Integrate agent-builder with agent-runtime knowledge readiness
-
-`agent-builder` is the meta-platform for creating, testing, deploying, researching, and monetizing domain-specific agents. It already has the strongest production loop among the app repos: Forge builder sims, per-agent scenarios, feedback trajectories, canaries, auto-research, multi-shot optimization, KB optimization, version history, sandbox execution, marketplace publishing, and Playwright-to-agent-eval reporting.
-
-The missing boundary is that generated agents and Forge runs do not yet have a first-class `agent-runtime` preflight. Failures caused by missing build spec context, missing user/business/domain data, unavailable integrations, missing secrets, stale KB evidence, sandbox/runtime gaps, or bad retrieval can still be absorbed as prompt/config failures.
-
-Package updates:
-
-- Upgrade `@tangle-network/agent-eval` from `^0.19.1` to `^0.20.0`.
-- Upgrade `@tangle-network/agent-knowledge` from `^1.0.0` to `^1.1.0`.
-- Add `@tangle-network/agent-runtime` `^0.2.0`.
-
-Required changes:
-
-- Add a server-side runtime module: `src/lib/.server/runtime/agent-builder-runtime.ts`, `src/lib/.server/runtime/requirements.ts`, and `src/lib/.server/runtime/events.ts`.
-- Expose helpers: `buildForgeKnowledgeRequirements(input)`, `buildPublishedAgentKnowledgeRequirements(input)`, `runForgeAgentTask(input)`, `runPublishedAgentTask(input)`, and `runtimeEventsToTraceMetadata(events)`.
-- Define Forge build requirements for creator intent, target user, domain/category, BuildSpec completeness and approval, expected artifact, success criteria, tools, integrations, APIs, credentials, secrets, sandbox availability, runtime image, repository/scaffold structure, generated agent config, pricing/marketplace/governance constraints, and user-approved assumptions.
-- Define generated-agent requirements for domain-specific user facts, company/business/product context, regulatory freshness, connected integrations, secrets, vault/knowledge pages, source freshness, scenario fixtures, and fallback policy.
-- Persist generated-agent runtime metadata with agent config/version metadata so forks and marketplace consumers inherit the right contract.
-- Wire `runAgentTask` into Forge builder sims: `src/lib/.server/eval/forge-builder-sim.ts`, `src/routes/api.agents.eval.builder-sim.ts`, and `src/routes/api.admin.builder-sim.run.ts`.
-- Wire scenario and eval runs through runtime: `src/routes/api.agents.$agentId.scenarios.run.ts`, `src/routes/api.agents.$agentId.eval.simulate.ts`, `src/routes/api.agents.$agentId.eval.refine.ts`, and `src/routes/api.agents.$agentId.eval.ts`.
-- Add readiness checks or metadata to production chat/sandbox chat: `src/routes/api.agents.$agentId.chat.ts`, `src/routes/api.agents.$agentId.sandbox.chat.ts`, and `src/routes/api.v1.agents.$slug.chat.completions.ts`.
-- Bridge `agent-knowledge@1.1.0` readiness with `src/routes/api.agents.$agentId.knowledge.index.ts`, `src/routes/api.agents.$agentId.knowledge.search.ts`, `src/routes/api.agents.$agentId.knowledge.discover.ts`, `src/routes/api.agents.$agentId.knowledge.write-blocks.ts`, and `src/lib/.server/kb/optimization.ts`.
-- Persist runtime events into trace/report surfaces: `src/lib/.server/eval/trace-store-d1.ts`, `src/lib/.server/eval/session.ts`, `src/lib/.server/eval/run-record-store.ts`, `src/lib/.server/eval/run-record-fields.ts`, and `e2e/reporters/agent-eval-reporter.ts`.
-- Preserve `task_start`, `readiness_start/end`, `questions_start/end`, `acquisition_start/end`, `control_start/end`, and `task_end`.
-- Report readiness score, blocking gaps, acquisition mode, evidence IDs, user questions, runtime status, and blocked-before-execution status.
-- Map failures to `knowledge_readiness_blocked`, `missing_user_data`, `missing_domain_data`, `missing_codebase_context`, `missing_runtime_context`, `missing_credentials`, `stale_external_data`, `bad_retrieval`, `insufficient_evidence`, `contradictory_evidence`, and `ambiguous_user_intent`.
-- Update `src/lib/.server/eval/failure-inspector.ts`, `src/lib/.server/eval/multi-shot-adapter.ts`, `src/lib/.server/eval/heuristic-researcher.ts`, `src/lib/.server/eval/auto-research-runner.ts`, and `src/lib/.server/eval/canary-cron.ts`.
-- Extend ASI responsible surfaces beyond `agent.config.systemPrompt`: `knowledge-requirements`, `data-acquisition`, `retrieval-policy`, `user-question-policy`, `runtime-environment`, `integration-policy`, `sandbox-policy`, and `agent.config.systemPrompt`.
-- Ensure auto-research does not mutate prompts when the dominant failure is missing KB pages, missing BuildSpec fields, missing secrets, unavailable sandbox, or stale evidence.
-- Persist runtime contracts across versions, publish, and forks: `src/lib/.server/versions.ts`, `src/routes/api.agents.$agentId.versions.ts`, `src/routes/api.agents.$agentId.versions.$versionId.revert.ts`, `src/routes/api.agents.$agentId.fork.ts`, `src/routes/api.agents.$agentId.fork.apply-update.ts`, and `src/routes/api.agents.$agentId.publish.ts`.
-- Add workbench/admin UI visibility for readiness on eval pages, research cycle pages, knowledge pages, chat/workbench blockers, and marketplace/published agent caveats. Do not expose private/secret requirement details to public consumers.
-
-Tests:
-
-- Forge sim blocks when BuildSpec or intent is incomplete.
-- Forge sim blocks or asks when required integration credentials are missing.
-- Scenario run records readiness metadata.
-- KB optimization reports no pages / too few labels as knowledge readiness failures.
-- Multi-shot ASI points to data-acquisition/retrieval-policy instead of `agent.config.systemPrompt` for missing knowledge.
-- Fork preserves runtime contract.
-- Public chat hides private/secret requirement details.
-- E2E reporter can include runtime readiness metadata.
-
-Acceptance criteria:
-
-- `agent-builder` depends on `agent-runtime@^0.2.0`, `agent-eval@^0.20.0`, and `agent-knowledge@^1.1.0`.
-- Forge builder sims run through `runAgentTask` or a thin typed wrapper.
-- Per-agent scenario/eval runs attach `KnowledgeReadinessReport` before execution.
-- KB search/optimization feeds readiness into runtime and traces.
-- Missing BuildSpec, missing credentials, missing KB pages, stale evidence, bad retrieval, and sandbox unavailability are classified as knowledge/runtime failures.
-- Multi-shot optimization can recommend acquisition/retrieval/user-question/runtime-policy changes instead of always mutating prompts.
-- Runtime requirements persist across config versions, publish, and fork flows.
-- Workbench/admin reports show readiness score, gaps, acquisition plan, runtime status, and blocked-before-execution runs.