@agentforge-io/sdk-console 0.2.0 → 0.4.0

package/README.md

@@ -135,11 +135,14 @@ Resource → methods → HTTP route (all JSON, bearer auth unless marked *public
 | `t.teams` | `list` `create` `get` `update` `delete` | `:T/teams[/:id]` (`list({ excludeTemplateSources })`; teams carry `templateSourceOf`) |
 | | `publication` / `listPublication` / `publish` | `GET :T/teams/:id/publication` · `GET :T/teams/publication` · `POST :T/teams/:id/publish` |
 | `t.teams.humanMembers` | `list` `add` `update` `remove` | `:T/teams/:id/human-members[/:userId]` |
+| `t.trace` | `listConversations` / `getConversation` | `GET :T/trace/conversations[?agentId&teamId&surface&model&toolName&hasError&q&from&to&cursor&limit]` · `GET :T/trace/conversations/:id` |
+| | `stats` / `timeseries` | `GET :T/trace/stats` · `GET :T/trace/timeseries[?bucket=hour\|day]` (same filters; `from`/`to` max 31 days) |
 | `t.variables` | `list` `get` `upsert` `remove` | `GET /tenants/:tid/variables[?q=]` · `GET\|PUT\|DELETE /tenants/:tid/variables/:key` (config has `value`; secrets only `valueHint`) |
 | `t.tools` | `grouped` | `GET /tools/grouped?tenantId=` |
 | `t.connectors` | `directory` / `facets` (sends `X-Tenant-Id`) | `GET /connectors/oauth/directory[/facets]` |
 | | `authorize` | `POST /connectors/oauth/:id/authorize?tenantId=&postAuthRedirect=` |
 | | `saveApiKey` | `POST /connectors/oauth/:id/api-key?tenantId=` |
+| | `disconnect` | `DELETE /connectors/oauth/:id?tenantId=` |
 | `templates` | `listPublic` / `getPublic` (public) | `GET /public/templates[/:id]` |
 | | `get` / `updateListing` / `listVersions` | `GET` / `PATCH /templates/:id` · `GET /templates/:id/versions` |
 | | `signListingAsset` | `POST /templates/:id/listing-assets/sign` |

package/dist/client.d.ts

@@ -6,6 +6,7 @@ import { ConnectorsResource } from './resources/connectors';
 import { InvitesResource, MembersResource, PublicInvitesResource } from './resources/members';
 import { MarketplaceResource } from './resources/marketplace';
 import { PlaygroundResource } from './resources/playground';
+import { TraceResource } from './resources/trace';
 import { TeamsResource } from './resources/teams';
 import { TemplatesResource, TenantTemplatesResource } from './resources/templates';
 import { TenantsResource } from './resources/tenants';
@@ -23,6 +24,8 @@ export declare class TenantScope {
     readonly templates: TenantTemplatesResource;
     readonly apps: AppsResource;
     readonly playground: PlaygroundResource;
+    /** Agent / team activity (conversations + span trace) and performance stats. */
+    readonly trace: TraceResource;
     /** Business data of the workspace (`{{config:KEY}}` / `{{secret:KEY}}`). */
     readonly variables: VariablesResource;
     constructor(http: HttpCore, tenantId: string);

package/dist/client.js

@@ -16,6 +16,7 @@ const connectors_1 = require("./resources/connectors");
 const members_1 = require("./resources/members");
 const marketplace_1 = require("./resources/marketplace");
 const playground_1 = require("./resources/playground");
+const trace_1 = require("./resources/trace");
 const teams_1 = require("./resources/teams");
 const templates_1 = require("./resources/templates");
 const tenants_1 = require("./resources/tenants");
@@ -36,6 +37,7 @@ class TenantScope {
         this.templates = new templates_1.TenantTemplatesResource(http, tenantId);
         this.apps = new apps_1.AppsResource(http, tenantId);
         this.playground = new playground_1.PlaygroundResource(http, tenantId);
+        this.trace = new trace_1.TraceResource(http, tenantId);
         this.variables = new variables_1.VariablesResource(http, tenantId);
     }
 }

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { parseOAuthReturn } from './oauth';
 export type { OAuthCrypto, OAuthReturn } from './oauth';
 export type { ConsoleClientOptions, FetchLike, QueryValue, RequestOptions, SignedOutReason } from './http';
 export * from './types';
+export * from './trace-types';
 export { AgentsResource, ChatTokensResource } from './resources/agents';
 export { AppsResource } from './resources/apps';
 export { AuthResource } from './resources/auth';
@@ -18,3 +19,4 @@ export { TemplatesResource, TenantTemplatesResource } from './resources/template
 export { TenantsResource } from './resources/tenants';
 export { ToolsResource } from './resources/tools';
 export { VariablesResource } from './resources/variables';
+export { TraceResource } from './resources/trace';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VariablesResource = exports.ToolsResource = exports.TenantsResource = exports.TenantTemplatesResource = exports.TemplatesResource = exports.TeamsResource = exports.TeamHumanMembersResource = exports.PlaygroundResource = exports.MarketplaceResource = exports.PublicInvitesResource = exports.MembersResource = exports.InvitesResource = exports.ConnectorsResource = exports.AuthResource = exports.AppsResource = exports.ChatTokensResource = exports.AgentsResource = exports.parseOAuthReturn = exports.MemoryTokenStore = exports.isApiError = exports.ApiError = exports.TenantScope = exports.ConsoleClient = void 0;
+exports.TraceResource = exports.VariablesResource = exports.ToolsResource = exports.TenantsResource = exports.TenantTemplatesResource = exports.TemplatesResource = exports.TeamsResource = exports.TeamHumanMembersResource = exports.PlaygroundResource = exports.MarketplaceResource = exports.PublicInvitesResource = exports.MembersResource = exports.InvitesResource = exports.ConnectorsResource = exports.AuthResource = exports.AppsResource = exports.ChatTokensResource = exports.AgentsResource = exports.parseOAuthReturn = exports.MemoryTokenStore = exports.isApiError = exports.ApiError = exports.TenantScope = exports.ConsoleClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "ConsoleClient", { enumerable: true, get: function () { return client_1.ConsoleClient; } });
 Object.defineProperty(exports, "TenantScope", { enumerable: true, get: function () { return client_1.TenantScope; } });
@@ -26,6 +26,7 @@ Object.defineProperty(exports, "MemoryTokenStore", { enumerable: true, get: func
 var oauth_1 = require("./oauth");
 Object.defineProperty(exports, "parseOAuthReturn", { enumerable: true, get: function () { return oauth_1.parseOAuthReturn; } });
 __exportStar(require("./types"), exports);
+__exportStar(require("./trace-types"), exports);
 var agents_1 = require("./resources/agents");
 Object.defineProperty(exports, "AgentsResource", { enumerable: true, get: function () { return agents_1.AgentsResource; } });
 Object.defineProperty(exports, "ChatTokensResource", { enumerable: true, get: function () { return agents_1.ChatTokensResource; } });
@@ -55,3 +56,5 @@ var tools_1 = require("./resources/tools");
 Object.defineProperty(exports, "ToolsResource", { enumerable: true, get: function () { return tools_1.ToolsResource; } });
 var variables_1 = require("./resources/variables");
 Object.defineProperty(exports, "VariablesResource", { enumerable: true, get: function () { return variables_1.VariablesResource; } });
+var trace_1 = require("./resources/trace");
+Object.defineProperty(exports, "TraceResource", { enumerable: true, get: function () { return trace_1.TraceResource; } });

package/dist/resources/connectors.d.ts

@@ -1,5 +1,5 @@
 import type { HttpCore } from '../http';
-import type { AuthorizeConnectorInput, ConnectorFacets, ConnectorStatus, ListConnectorsInput } from '../types';
+import type { AuthorizeConnectorInput, ConnectorFacets, ConnectorStatus, DisconnectConnectorResult, ListConnectorsInput } from '../types';
 export declare class ConnectorsResource {
     private readonly http;
     private readonly tenantId;
@@ -22,4 +22,10 @@ export declare class ConnectorsResource {
     saveApiKey(connectorId: string, apiKey: string): Promise<{
         connectorId: string;
     }>;
+    /** `DELETE /connectors/oauth/:id?tenantId=`: removes this workspace's
+     *  connection (owner/admin; best-effort revoke at the provider). Idempotent:
+     *  `disconnected: false` when there was nothing to remove. A
+     *  `postAuthRedirect` outside the platform allow-list makes `authorize`
+     *  fail with `ApiError` code `post_auth_redirect_not_allowed`. */
+    disconnect(connectorId: string): Promise<DisconnectConnectorResult>;
 }

package/dist/resources/connectors.js

@@ -1,6 +1,7 @@
 "use strict";
 // connectors for one workspace (`forTenant(id).connectors`): the directory
-// with per-workspace `connected` flags, and the OAuth / API-key connect flow.
+// with per-workspace `connected` flags, the OAuth / API-key connect flow and
+// disconnect.
 //
 // The directory resolves the workspace from the `X-Tenant-Id` header (the JWT
 // carries no tenant), so these calls send it. A browser therefore needs CORS
@@ -43,5 +44,15 @@ class ConnectorsResource {
             body: { apiKey },
         });
     }
+    /** `DELETE /connectors/oauth/:id?tenantId=`: removes this workspace's
+     *  connection (owner/admin; best-effort revoke at the provider). Idempotent:
+     *  `disconnected: false` when there was nothing to remove. A
+     *  `postAuthRedirect` outside the platform allow-list makes `authorize`
+     *  fail with `ApiError` code `post_auth_redirect_not_allowed`. */
+    async disconnect(connectorId) {
+        return this.http.request('DELETE', `/connectors/oauth/${(0, http_1.seg)(connectorId)}`, {
+            query: { tenantId: this.tenantId },
+        });
+    }
 }
 exports.ConnectorsResource = ConnectorsResource;

package/dist/resources/trace.d.ts

@@ -0,0 +1,16 @@
+import type { HttpCore } from '../http';
+import type { TraceConversationDetail, TraceConversationList, TraceConversationListQuery, TraceStats, TraceStatsQuery, TraceTimeseries, TraceTimeseriesQuery } from '../trace-types';
+export declare class TraceResource {
+    private readonly http;
+    private readonly tenantId;
+    constructor(http: HttpCore, tenantId: string);
+    private get base();
+    /** `GET .../trace/conversations`: keyset-paginated, last activity desc. 400 on a bad window/cursor. */
+    listConversations(query?: TraceConversationListQuery): Promise<TraceConversationList>;
+    /** `GET .../trace/conversations/:conversationId`: transcript + per-turn span tree. 404 if not in this workspace. */
+    getConversation(conversationId: string): Promise<TraceConversationDetail>;
+    /** `GET .../trace/stats`: tool / model / latency / sanitizer aggregates over a window. */
+    stats(query?: TraceStatsQuery): Promise<TraceStats>;
+    /** `GET .../trace/timeseries`: per-bucket volume, latency percentiles, phases, outcomes, models, plus previous window. */
+    timeseries(query?: TraceTimeseriesQuery): Promise<TraceTimeseries>;
+}

package/dist/resources/trace.js

@@ -0,0 +1,39 @@
+"use strict";
+// Agent / team activity of one workspace (`forTenant(id).trace`): traced
+// conversations with the per-turn span tree, and performance aggregates.
+// Read-only. Roles owner | admin | member; members get no span bodies,
+// sanitizer texts or non-channel transcripts (the fields are absent).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceResource = void 0;
+const http_1 = require("../http");
+const iso = (d) => (d instanceof Date ? d.toISOString() : d);
+/** Serialize a query: `Date` -> ISO string, undefined dropped by buildQuery. */
+function toQuery(q) {
+    return { ...q, from: iso(q.from), to: iso(q.to) };
+}
+class TraceResource {
+    constructor(http, tenantId) {
+        this.http = http;
+        this.tenantId = tenantId;
+    }
+    get base() {
+        return `/admin/tenants/${(0, http_1.seg)(this.tenantId)}/trace`;
+    }
+    /** `GET .../trace/conversations`: keyset-paginated, last activity desc. 400 on a bad window/cursor. */
+    async listConversations(query = {}) {
+        return this.http.request('GET', `${this.base}/conversations`, { query: toQuery({ ...query }) });
+    }
+    /** `GET .../trace/conversations/:conversationId`: transcript + per-turn span tree. 404 if not in this workspace. */
+    async getConversation(conversationId) {
+        return this.http.request('GET', `${this.base}/conversations/${(0, http_1.seg)(conversationId)}`);
+    }
+    /** `GET .../trace/stats`: tool / model / latency / sanitizer aggregates over a window. */
+    async stats(query = {}) {
+        return this.http.request('GET', `${this.base}/stats`, { query: toQuery({ ...query }) });
+    }
+    /** `GET .../trace/timeseries`: per-bucket volume, latency percentiles, phases, outcomes, models, plus previous window. */
+    async timeseries(query = {}) {
+        return this.http.request('GET', `${this.base}/timeseries`, { query: toQuery({ ...query }) });
+    }
+}
+exports.TraceResource = TraceResource;

package/dist/trace-types.d.ts

@@ -0,0 +1,423 @@
+export type TraceSpanKind = 'turn' | 'llm_call' | 'tool_call' | 'delegation' | 'router_decision' | 'sanitizer' | 'gate' | 'approval' | 'error';
+export type TraceSpanStatus = 'ok' | 'error' | 'skipped' | 'deduped' | 'blocked' | 'denied' | 'aborted' | 'rejected';
+/** A date as ISO-8601 string or `Date` (serialized with `toISOString()`). Window max 31 days; default last 7. */
+export type TraceDateInput = string | Date;
+/** Filters shared by list / stats / timeseries. All optional. */
+export interface TraceFilterQuery {
+    agentId?: string;
+    /** uuid */
+    teamId?: string;
+    surface?: string;
+    /** Matches served OR requested model. */
+    model?: string;
+    toolName?: string;
+    hasError?: boolean;
+}
+export interface TraceWindowQuery {
+    /** Inclusive. Default: `to` - 7 days. */
+    from?: TraceDateInput;
+    /** Exclusive. Default: now. */
+    to?: TraceDateInput;
+}
+/** `GET trace/conversations`. `surface`/`model`/`toolName`/`hasError` select CONVERSATIONS here. */
+export interface TraceConversationListQuery extends TraceFilterQuery, TraceWindowQuery {
+    /** Text search over messages, 2-100 chars; only effective for owner/admin. */
+    q?: string;
+    /** `nextCursor` of the previous page. */
+    cursor?: string;
+    /** 1..100, default 25. */
+    limit?: number;
+}
+/** `GET trace/stats`. Per-turn filters select ROOT TURNS. */
+export interface TraceStatsQuery extends TraceFilterQuery, TraceWindowQuery {
+}
+/** `GET trace/timeseries`. Default bucket: hour for windows <= 48h, else day (max 744 buckets). */
+export interface TraceTimeseriesQuery extends TraceFilterQuery, TraceWindowQuery {
+    bucket?: TraceBucketUnit;
+}
+/**
+ * How a turn ended (AGF-RUN-TRACE-2c; mirrors core's `TurnOutcome`).
+ *
+ * Error semantics of the list (`errorCount` / `hasError` / `emptyCount`):
+ *  - `errorCount` counts spans with status error | rejected | blocked, EXCEPT
+ *    the ones that are an expected gate rather than a failure: a turn span whose
+ *    outcome is `awaiting_approval` / `tool_blocked` (core reports those as
+ *    `status:'error'` on non-stream paths), and the `blocked` tool_call spans
+ *    of a trace that is `awaiting_approval` (an approval request is not an error).
+ *    A policy-blocked tool (`tool_blocked`) still counts as an error.
+ *  - `empty_response` turns (the model finished without text) are their own
+ *    category, `emptyCount`, NOT part of `errorCount`, but `hasError=true`
+ *    includes them (and `hasError=false` excludes them).
+ */
+export type TraceTurnOutcome = 'replied' | 'empty_response' | 'awaiting_approval' | 'tool_blocked' | 'error' | 'aborted';
+export interface TraceConversationItem {
+    conversationId: string;
+    /** Agent of the first root turn (slug or uuid, as the runtime reported it). */
+    agentId: string | null;
+    agentName: string | null;
+    teamId: string | null;
+    surface: string | null;
+    /** Earliest / latest span activity INSIDE the requested window. */
+    firstAt: string;
+    lastAt: string;
+    /** Root turns only (member turns are not counted). */
+    turnCount: number;
+    llmCallCount: number;
+    toolCallCount: number;
+    /** Failing spans (see `TraceTurnOutcome` for the exact rule; approval gates are not errors). */
+    errorCount: number;
+    /** Root turns that ended `empty_response`. Included by the `hasError` filter, not in `errorCount`. */
+    emptyCount: number;
+    /** Distinct served model, falling back to the requested one. */
+    models: string[];
+    totalCostMicros: number | null;
+    inputTokens: number;
+    outputTokens: number;
+    /** p50 of root-turn durations (ms), null when no turn has a duration. */
+    p50TurnMs: number | null;
+    /** Last message text (<= 200 chars); null when not readable by this viewer or no message. */
+    lastMessagePreview: string | null;
+    lastMessageRole: string | null;
+}
+export interface TraceConversationList {
+    items: TraceConversationItem[];
+    /** Opaque; pass back as `cursor`. null when there is no further page. */
+    nextCursor: string | null;
+    window: {
+        from: string;
+        to: string;
+    };
+    /** Present when `q` was used: the search scans at most this many most-recent conversations per page. */
+    qScanCap?: number;
+}
+export interface TraceSpanView {
+    id: string;
+    seq: number;
+    kind: TraceSpanKind;
+    /** null for span kinds this server version does not know, when viewed below full payload access. */
+    name: string | null;
+    phase: string | null;
+    iteration: number | null;
+    startedAt: string;
+    durationMs: number | null;
+    status: TraceSpanStatus;
+    modelRequested: string | null;
+    modelServed: string | null;
+    routeReason: string | null;
+    routeTrigger: string | null;
+    keyOrigin: string | null;
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheCreationTokens: number | null;
+    costMicros: number | null;
+    stopReason: string | null;
+    toolCount: number | null;
+    /**
+     * Phase timings (AGF-AGENT-PERF-CHARTS); all null on rows written before they
+     * existed and wherever the platform could not measure them.
+     *  - llm_call: `providerWaitMs` = platform provider entry -> vendor call (BYOK
+     *    lookup + provider resolution), `ttftMs` = vendor call -> first token.
+     *    Both are part of `durationMs`.
+     *  - root turn: `prepMs` = request/webhook accept -> runtime turn start (NOT part
+     *    of `durationMs`), `firstTextMs` = accept -> first user-visible text.
+     */
+    providerWaitMs: number | null;
+    ttftMs: number | null;
+    prepMs: number | null;
+    firstTextMs: number | null;
+    /** turn spans: how the turn ended; null on other spans and on turn rows written before core reported it. */
+    outcome: TraceTurnOutcome | null;
+    /** delegation spans: the member's trace id; `memberTrace` is that trace when present in this conversation. */
+    childTraceId: string | null;
+    memberTrace?: TraceNode;
+    input?: unknown;
+    output?: unknown;
+    errorMessage?: string | null;
+}
+export interface TraceRollup {
+    /** Root turn span duration, else derived (first span start -> last span end). */
+    durationMs: number | null;
+    costMicros: number | null;
+    inputTokens: number;
+    outputTokens: number;
+    models: string[];
+    llmCallCount: number;
+    toolCallCount: number;
+    errorCount: number;
+    /** Turns (own + nested members) that ended `empty_response`. */
+    emptyCount: number;
+    /** Turn span status; `incomplete` ONLY when no turn span was recorded (e.g. the process died mid-turn). */
+    status: TraceSpanStatus | 'incomplete';
+    /** Root turn outcome (`empty_response`, `awaiting_approval`, ... never `incomplete`); null when
+     *  there is no turn span or it predates outcome reporting. Prefer `outcome ?? status` for display. */
+    outcome: TraceTurnOutcome | null;
+}
+export interface TraceNode {
+    traceId: string;
+    parentTraceId: string | null;
+    agentId: string | null;
+    agentName: string | null;
+    surface: string | null;
+    /** Inbound message that triggered the turn (traceContext.messageId), when known. */
+    messageId: string | null;
+    /** Same as `rollup.outcome` of the turn span of THIS trace (not of nested members). */
+    outcome: TraceTurnOutcome | null;
+    startedAt: string;
+    /** Own spans + nested member traces, ordered by seq. */
+    spans: TraceSpanView[];
+    /** Rollup including nested member traces. */
+    rollup: TraceRollup;
+    /** Member turn whose parent trace is not in this conversation's data (aged out / dropped). */
+    orphan?: boolean;
+    /** Members whose parent exists but no delegation span points at them. */
+    unlinkedMembers?: TraceNode[];
+    /** Channel gate verdict for the message that triggered this turn. */
+    gate?: TraceSpanView;
+    /**
+     * Link to the transcript (root turns only). `turn_id` = exact: the assistant row whose
+     * `metadata.turnId` equals this trace id (and/or the ids the turn span recorded);
+     * `time_window` = best-effort fallback for turns without any exact id (written before core
+     * stamped `metadata.turnId`).
+     */
+    link?: {
+        userMessageId: string | null;
+        assistantMessageId: string | null;
+        method: 'turn_id' | 'time_window';
+    };
+}
+export interface TraceMessageView {
+    id: string;
+    role: string;
+    /** null (and `contentVisible:false`) when this viewer may not read the transcript. */
+    content: string | null;
+    contentVisible: boolean;
+    createdAt: string;
+}
+export interface TraceConversationDetail {
+    conversationId: string;
+    agentId: string | null;
+    agentName: string | null;
+    teamId: string | null;
+    surface: string | null;
+    /** Prefix of the conversation owner key: channel | chat-token | inbox | whatsapp | voice | app-user | ... */
+    userKind: string | null;
+    messages: TraceMessageView[];
+    turns: TraceNode[];
+    /** True when the 5000-span cap was hit (the most recent spans were cut). */
+    truncated: boolean;
+}
+export interface TraceToolStat {
+    tool: string;
+    calls: number;
+    errors: number;
+    deduped: number;
+    blocked: number;
+    /** Over executed calls (status ok|error); deduped/blocked excluded. */
+    p50Ms: number | null;
+    p95Ms: number | null;
+}
+export interface TraceModelStat {
+    /** Served model, falling back to the requested one when attribution was unavailable. */
+    model: string;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    costMicros: number | null;
+}
+export interface TraceStats {
+    window: {
+        from: string;
+        to: string;
+    };
+    /**
+     * Without per-turn filters exactly `{ agentId, teamId }` (the response is
+     * unchanged from before AGF-PERF-FILTER-TURN). With any of them it also
+     * carries `surface` / `model` / `toolName` / `hasError`.
+     */
+    filter: {
+        agentId: string | null;
+        teamId: string | null;
+        surface?: string | null;
+        model?: string | null;
+        toolName?: string | null;
+        hasError?: boolean | null;
+    };
+    /**
+     * Present only when a per-turn filter is set: every aggregate counts only
+     * the spans of the matching root turns' families (own trace + delegated
+     * member traces, one hop); spans outside any root turn are left out.
+     */
+    filterScope?: 'turn';
+    tools: TraceToolStat[];
+    models: {
+        mix: TraceModelStat[];
+        llmCalls: number;
+        /** llm_calls with a served model attributed. */
+        attributed: number;
+        /**
+         * Calls the router or the provider moved off what was asked: a route
+         * reason is set, or a concrete requested id was served by another model.
+         * An `adaptive:*` tier resolving to its model, or a dated id of the same
+         * model (`claude-haiku-4-5` -> `claude-haiku-4-5-20251001`), is not one.
+         */
+        servedDiffersFromRequested: number;
+        routeReasons: Array<{
+            reason: string;
+            count: number;
+        }>;
+        /** Top requested -> served pairs (<= 50). */
+        pairs: Array<{
+            requested: string | null;
+            served: string;
+            reason: string | null;
+            count: number;
+        }>;
+    };
+    turns: {
+        count: number;
+        p50Ms: number | null;
+        p95Ms: number | null;
+        byStatus: Array<{
+            status: string;
+            count: number;
+        }>;
+        /** Root turns by outcome; turn rows without one (pre-2c) are grouped as `unknown`. */
+        byOutcome: Array<{
+            outcome: string;
+            count: number;
+        }>;
+    };
+    sanitizer: Array<{
+        status: string;
+        count: number;
+        changed: number;
+        avgMs: number | null;
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+    errorTurns: {
+        count: number;
+        recent: Array<{
+            traceId: string;
+            conversationId: string | null;
+            agentId: string | null;
+            startedAt: string;
+            /** Full access only. */
+            errorMessage?: string | null;
+        }>;
+    };
+}
+export type TraceBucketUnit = 'hour' | 'day';
+/**
+ * Same names as the Conversations list filters, but `surface` / `model` /
+ * `toolName` / `hasError` select ROOT TURNS here (`filterScope: 'turn'`), while
+ * the list keeps selecting conversations.
+ */
+export interface TraceTimeseriesFilter {
+    agentId: string | null;
+    teamId: string | null;
+    surface: string | null;
+    model: string | null;
+    toolName: string | null;
+    /** `true` = only turns with a failing span (own or delegated) / empty reply, `false` = exclude them, `null` = all. */
+    hasError: boolean | null;
+}
+/**
+ * p50 (ms) of where a root turn's time goes, over the turns that have phase
+ * data (`phaseSamples`). A turn's phases add up to its `totalMs`:
+ *   totalMs = prep + providerWait + ttft + generation + tools + sanitizer + rest
+ * with `rest` the remainder (never negative): runtime work before the first LLM
+ * call (history load, connector tools resolution), orchestrator planning calls
+ * (not measured around the platform provider), persistence and delivery.
+ *  - `tools` is the wall-clock UNION of the turn's tool calls and delegated
+ *    member runs (parallel calls are not double counted).
+ *  - a phase a turn does not have counts as 0 (a turn without tools has tools = 0).
+ * p50s of different phases do not add up to the p50 of the total; they describe
+ * the typical turn phase by phase.
+ */
+export interface TracePhaseP50 {
+    prep: number | null;
+    providerWait: number | null;
+    ttft: number | null;
+    generation: number | null;
+    tools: number | null;
+    sanitizer: number | null;
+    rest: number | null;
+}
+/** Stats of a set of root turns (one bucket, the whole window, or the previous window). */
+export interface TraceTimeseriesStats {
+    /** Root turns (member runs excluded). */
+    turns: number;
+    /** Root turns that failed (status error, excluding approval / policy gates). */
+    errors: number;
+    /** Time from accept to the first user-visible text. Over `firstTextSamples` turns; null without samples. */
+    p50FirstTextMs: number | null;
+    p95FirstTextMs: number | null;
+    firstTextSamples: number;
+    /** Full reply time: accept -> end of turn (`prep` + `duration`; `duration` alone where `prep` is unknown). */
+    p50TotalMs: number | null;
+    p95TotalMs: number | null;
+    phases: TracePhaseP50;
+    /** Turns with phase data; rows written before the phase fields existed are excluded from `phases`. */
+    phaseSamples: number;
+    /** Root turns by surface (`unknown` when none was recorded). */
+    bySurface: Record<string, number>;
+    /** Root turns by outcome (`unknown` for rows that predate outcome reporting). */
+    byOutcome: Record<string, number>;
+    /** LLM calls (root turns + their delegated members) by served model, falling back to the requested one. */
+    byModel: Record<string, number>;
+    /** LLM calls the router or the provider moved off the requested model (same rule as `stats`). */
+    reroutes: number;
+    /** owner / admin / platform admin only; ABSENT for members. Integer micro-USD at list price. null = no price configured. */
+    costMicros?: number | null;
+    /** owner / admin / platform admin only; ABSENT for members. cache_read / (input + cache_read + cache_creation), 0..1; null without LLM tokens. */
+    cacheReadRatio?: number | null;
+}
+export interface TraceTimeseriesBucket extends TraceTimeseriesStats {
+    /** ISO-8601 UTC start of the bucket (hour or day, aligned in UTC). Empty buckets are present with zero turns. */
+    start: string;
+}
+export interface TraceTimeseriesAgentRow {
+    agentId: string;
+    agentName: string | null;
+    turns: number;
+    errors: number;
+    /** errors / turns, 0..1. */
+    errorRate: number;
+    p50FirstTextMs: number | null;
+    p95FirstTextMs: number | null;
+    p50TotalMs: number | null;
+    /** owner / admin / platform admin only; ABSENT for members. */
+    costMicros?: number | null;
+}
+/** Window-level stats: the bucket stats plus how many root turns the filters kept. */
+export interface TraceTimeseriesWindowStats extends TraceTimeseriesStats {
+    /**
+     * Root turns of the same window + agent / team scope with NO surface /
+     * model / toolName / hasError filter. Equals `turns` when none is set.
+     */
+    unfilteredTurns: number;
+}
+export interface TraceTimeseries {
+    window: {
+        from: string;
+        to: string;
+    };
+    bucket: TraceBucketUnit;
+    filter: TraceTimeseriesFilter;
+    /** The filters select root turns, not conversations (always `'turn'`). */
+    filterScope: 'turn';
+    buckets: TraceTimeseriesBucket[];
+    /** The whole window. */
+    summary: TraceTimeseriesWindowStats;
+    /** The window of the same length right before `window`, for deltas. */
+    previous: TraceTimeseriesWindowStats & {
+        window: {
+            from: string;
+            to: string;
+        };
+    };
+    /** Global scope only (no agentId / teamId): per-agent comparison, top 50 by turns. */
+    agents?: TraceTimeseriesAgentRow[];
+}

package/dist/trace-types.js

@@ -0,0 +1,10 @@
+"use strict";
+// Wire types of the trace read API (`admin/tenants/:tenantId/trace/*`). Mirrors
+// agentforge-platform apps/server/src/modules/trace/trace-read.types.ts.
+//
+// Conventions: timestamps are ISO-8601 UTC strings; `*Micros` are integer
+// micro-USD at LIST price (null = no price configured); `T | null` = not
+// recorded. "Payload" fields (`input`, `output`, `errorMessage`, sanitizer
+// texts, cost on some aggregates) are ABSENT (not null) for workspace members
+// below owner/admin: see `TraceConversationDetail.messages[].contentVisible`.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.ts

@@ -1007,3 +1007,13 @@ export interface PublisherErrorBody {
     message: string;
     issues?: TeamPublicationIssue[];
 }
+/** `DELETE /connectors/oauth/:id` result. */
+export interface DisconnectConnectorResult {
+    ok: true;
+    connectorId: string;
+    tenantId: string;
+    /** False when the workspace had no connection (idempotent). */
+    disconnected: boolean;
+    /** True when the provider confirmed the token revoke (best effort). */
+    revokedAtProvider: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/sdk-console",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "User-session SDK for admin clients of the AgentForge platform (Expo / React Native, web, Node). Dashboard JWT auth with refresh, tenant scoping, typed resources.",
   "license": "MIT",
   "repository": {