@xopcai/xopc 0.0.332 → 0.0.334

package/dist/src/scenes/taskFollowUp/service.js

@@ -17,7 +17,7 @@ import { sceneContentHash } from "../contracts.js";
 import { SceneConflictError, SceneNotFoundError, SceneRepository } from "../repository.js";
 import { SceneSetupError } from "../service.js";
 import { ScenePreferenceService } from "../preferences.js";
-import { sourceIdentity, taskFollowUpInputSchema, taskFollowUpTemplate } from "./contracts.js";
+import { sourceIdentity, taskFollowUpInputSchema } from "./contracts.js";
 import { FollowUpAgentExecutor } from "./agentExecutor.js";
 import { VerificationTerminationUnknownError, verifyTaskWorkspace } from "../../agent/commands/approved-verification.js";
 import { TaskResources } from "./resources.js";
@@ -39,7 +39,8 @@ const delegationHash = (input) => {
 	});
 };
 /** Scene orchestration owns source cursors, not a second Task/TaskRun lifecycle. */
-var TaskFollowUpService = class {
+var SceneTaskExecutionService = class {
+	id = "task";
 	branches;
 	scenes;
 	tasks = new TaskRepository();
@@ -59,21 +60,12 @@ var TaskFollowUpService = class {
 		this.deps = deps;
 		this.scenes = new SceneRepository(db);
 		this.branches = new TaskBranchInventory(db);
-		this.scenes.installTemplate(taskFollowUpTemplate);
 		this.executor = deps.executor ?? new FollowUpAgentExecutor(() => resolveModel(resolveModelSelector(deps.config(), resolveDefaultAgentId(), "@reasoning")), deps.config);
 		this.sources = deps.sources;
 		this.resources = new TaskResources({
 			stateDir: deps.stateDir,
 			worktrees: deps.worktrees
 		});
-		for (const row of db.prepare(`SELECT b.* FROM scene_task_bindings b JOIN scene_activations a ON a.id = b.activation_id
-      WHERE a.template_key = 'slack-development'`).all()) {
-			const input = taskFollowUpInputSchema.parse(JSON.parse(row.input_json));
-			db.prepare("UPDATE scene_task_bindings SET source_key = ? WHERE activation_id = ?").run(sourceIdentity(this.principal(row.activation_id), input.source), row.activation_id);
-			db.prepare("UPDATE scene_activations SET template_key = 'task-follow-up', template_version = '1.0.0' WHERE id = ?").run(row.activation_id);
-		}
-		db.prepare(`DELETE FROM scene_template_versions WHERE template_key = 'slack-development'
-      AND NOT EXISTS (SELECT 1 FROM scene_activations WHERE template_key = 'slack-development')`).run();
 	}
 	binding(id) {
 		const row = this.db.prepare("SELECT * FROM scene_task_bindings WHERE activation_id = ?").get(id);
@@ -109,9 +101,11 @@ var TaskFollowUpService = class {
 			return false;
 		}
 	}
-	async preflight(principal, value) {
+	async preflight(principal, template, value) {
+		if (template.execution.kind !== this.id || template.contextProviders.length !== 1 || template.contextProviders[0] !== "connected_source" || !template.triggers.some((trigger) => trigger.type === "event" && trigger.eventType === "source.changed") || !template.allowedOutcomeKinds.includes("receipt")) throw new SceneConflictError("Template is incompatible with the task execution adapter");
 		const input = this.parse(value);
 		const missing = [];
+		if (input.capabilities.some((capability) => capability !== "workspace.read" && !template.allowedEffectHandlers.includes(capability))) missing.push("capability_not_allowed");
 		if (!this.source(input).authorized(principal, input.source.reference)) missing.push("source_read_permission");
 		const project = input.projectId ? new ProjectStore().get(input.projectId) : void 0;
 		if (input.projectId && (!project || project.ownerId && project.ownerId !== principal.ownerId)) missing.push("project_access");
@@ -150,28 +144,30 @@ var TaskFollowUpService = class {
 			missing
 		};
 	}
-	async create(principal, value) {
+	async create(principal, template, value) {
 		const input = this.parse(value);
 		const key = sourceIdentity(principal, input.source);
-		const existing = this.db.prepare("SELECT activation_id, input_json FROM scene_task_bindings WHERE source_key = ?").get(key);
+		const existing = this.db.prepare(`SELECT b.activation_id, b.input_json, a.template_key, a.template_version
+      FROM scene_task_bindings b JOIN scene_activations a ON a.id = b.activation_id WHERE b.source_key = ?`).get(key);
 		if (existing) {
-			if (delegationHash(JSON.parse(String(existing.input_json))) !== delegationHash(input)) throw new SceneConflictError("This source is already delegated with a different goal or project");
+			if (existing.template_key !== template.key || existing.template_version !== template.version || delegationHash(JSON.parse(String(existing.input_json))) !== delegationHash(input)) throw new SceneConflictError("This source is already delegated with a different template, goal or project");
 			return this.get(principal, String(existing.activation_id));
 		}
-		const readiness = await this.preflight(principal, input);
+		const readiness = await this.preflight(principal, template, input);
 		if (!readiness.ready) throw new SceneSetupError(readiness.missing);
 		const snapshot = await this.source(input).read(principal, input.source.reference, AbortSignal.any([this.stopController.signal, AbortSignal.timeout(3e4)]));
 		this.stopController.signal.throwIfAborted();
 		if (!this.source(input).authorized(principal, input.source.reference)) throw new SceneSetupError(["source_read_permission"]);
 		const id = runSqliteWriteTransaction(() => {
-			const concurrent = this.db.prepare("SELECT activation_id, input_json FROM scene_task_bindings WHERE source_key = ?").get(key);
+			const concurrent = this.db.prepare(`SELECT b.activation_id, b.input_json, a.template_key, a.template_version
+        FROM scene_task_bindings b JOIN scene_activations a ON a.id = b.activation_id WHERE b.source_key = ?`).get(key);
 			if (concurrent) {
-				if (delegationHash(JSON.parse(String(concurrent.input_json))) !== delegationHash(input)) throw new SceneConflictError("This source is already delegated with a different goal or project");
+				if (concurrent.template_key !== template.key || concurrent.template_version !== template.version || delegationHash(JSON.parse(String(concurrent.input_json))) !== delegationHash(input)) throw new SceneConflictError("This source is already delegated with a different template, goal or project");
 				return String(concurrent.activation_id);
 			}
 			const activation = this.scenes.createActivation(principal, {
-				templateKey: taskFollowUpTemplate.key,
-				templateVersion: taskFollowUpTemplate.version,
+				templateKey: template.key,
+				templateVersion: template.version,
 				goal: input.goal,
 				scope: input.projectId ? {
 					kind: "project",
@@ -184,7 +180,7 @@ var TaskFollowUpService = class {
 				}
 			}, key);
 			const created = this.application.create({
-				idempotencyKey: `scene-task-follow-up:${key}`,
+				idempotencyKey: `scene-task-execution:${key}`,
 				title: input.goal.slice(0, 200),
 				projectId: input.projectId,
 				ownerId: principal.ownerId,
@@ -263,6 +259,12 @@ var TaskFollowUpService = class {
       JOIN scene_activations a ON a.id = b.activation_id JOIN scene_preferences p ON p.owner_id = a.owner_id AND p.workspace_id = a.workspace_id
       WHERE b.task_id = ? AND json_extract(p.preferences_json, '$.notificationsMuted') = 1`).get(taskId);
 	}
+	listProjectBranches(principal, projectId) {
+		return this.branches.list(principal, projectId);
+	}
+	associateBranch(principal, input) {
+		return this.branches.associate(principal, input);
+	}
 	async configure(principal, id, expectedRevision, value) {
 		const activation = this.scenes.getActivation(principal, id);
 		const row = this.binding(id);
@@ -271,7 +273,8 @@ var TaskFollowUpService = class {
 		const task = this.tasks.require(row.task_id);
 		if (activation.status !== "paused" || task.phase === "closed" || row.executing_run_id || this.runs.getActiveRoot(task.id)) throw new SceneConflictError("Pause and wait for the current run before changing instructions or permissions");
 		if (sourceIdentity(principal, old.source) !== sourceIdentity(principal, input.source) || old.projectId !== input.projectId || old.resource !== input.resource) throw new SceneConflictError("Source and resource identity cannot change on an existing task");
-		const readiness = await this.preflight(principal, input);
+		const template = this.scenes.getTemplate(activation.templateKey, activation.templateVersion);
+		const readiness = await this.preflight(principal, template, input);
 		if (!readiness.ready) throw new SceneSetupError(readiness.missing);
 		runSqliteWriteTransaction(() => {
 			if (this.binding(id).executing_run_id || this.runs.getActiveRoot(task.id)) throw new SceneConflictError("Task started while changing permissions");
@@ -352,7 +355,7 @@ var TaskFollowUpService = class {
 				},
 				actor: {
 					kind: "system",
-					id: "scene-task-follow-up"
+					id: "scene-task-execution"
 				}
 			}).ok) throw new Error("Task contract revision failed");
 		}
@@ -390,7 +393,7 @@ var TaskFollowUpService = class {
 			},
 			actor: {
 				kind: "system",
-				id: "scene-task-follow-up"
+				id: "scene-task-execution"
 			}
 		});
 	}
@@ -479,8 +482,10 @@ var TaskFollowUpService = class {
 		if (!raw) return false;
 		const id = String(raw.activation_id);
 		if (this.active.has(id)) throw new SceneConflictError("Task follow-up already has a writer");
+		const intentId = this.executionIntent(id, runId);
+		const sceneRun = this.scenes.claimIntentForAdapter(this.principal(id), id, intentId, this.id, `task:${runId}`, Date.now(), 31e4);
 		const controller = new AbortController();
-		const promise = this.execute(id, runId, conversationId, AbortSignal.any([
+		const promise = this.execute(id, runId, conversationId, sceneRun, AbortSignal.any([
 			controller.signal,
 			this.stopController.signal,
 			AbortSignal.timeout(3e5)
@@ -494,9 +499,40 @@ var TaskFollowUpService = class {
 		await promise;
 		return true;
 	}
-	async execute(id, runId, conversationId, signal) {
+	executionIntent(id, taskRunId) {
+		const principal = this.principal(id);
+		const activation = this.scenes.getActivation(principal, id);
+		const trigger = this.scenes.getTemplate(activation.templateKey, activation.templateVersion).triggers.find((item) => item.type === "event" && item.eventType === "source.changed");
+		if (!trigger) throw new SceneConflictError("Scene has no source change trigger");
+		const row = this.binding(id);
+		const revision = this.db.prepare("SELECT source_hash, observed_at FROM scene_task_revisions WHERE activation_id = ? AND revision = ?").get(id, row.observed_revision);
+		if (!revision) throw new SceneConflictError("Scene source revision is unavailable");
+		const input = taskFollowUpInputSchema.parse(JSON.parse(row.input_json));
+		const occurrenceKey = sceneContentHash({
+			activationRevision: activation.revision,
+			sourceRevision: row.observed_revision,
+			taskRunId
+		});
+		const accountIds = this.source(input).accountIds(input.source.reference);
+		const now = Date.now();
+		return this.scenes.acceptTrigger(principal, id, {
+			triggerKey: trigger.id,
+			occurrenceKey,
+			dueAt: now,
+			event: {
+				source: input.source.provider,
+				sourceEventId: revision.source_hash,
+				eventType: trigger.eventType,
+				subjectId: row.source_key,
+				occurredAt: revision.observed_at,
+				...accountIds.length === 1 ? { accountId: accountIds[0] } : {}
+			}
+		}, now);
+	}
+	async execute(id, runId, conversationId, sceneRun, signal) {
 		const row = this.binding(id);
 		const activation = this.scenes.getActivation(this.principal(id), id);
+		const template = this.scenes.getTemplate(activation.templateKey, activation.templateVersion);
 		const input = taskFollowUpInputSchema.parse(JSON.parse(row.input_json));
 		const revision = row.observed_revision;
 		const contractVersion = this.runs.require(runId).contractVersion;
@@ -508,6 +544,7 @@ var TaskFollowUpService = class {
 		const guard = () => {
 			if (terminationUnknown) throw new VerificationTerminationUnknownError("Verification termination is unknown");
 			signal.throwIfAborted();
+			if (!this.scenes.getRunInput(sceneRun, Date.now())) throw new Error("Scene execution lease changed");
 			resource?.assertLive();
 			const current = this.binding(id);
 			const task = this.tasks.require(row.task_id);
@@ -521,6 +558,7 @@ var TaskFollowUpService = class {
 				owner: leaseOwner,
 				leaseMs: 6e4
 			});
+			this.scenes.renewLease(sceneRun, Date.now(), 31e4);
 		}, 15e3);
 		heartbeat.unref();
 		try {
@@ -578,7 +616,7 @@ var TaskFollowUpService = class {
 				runId,
 				conversationId,
 				workspace: resource?.rootPath ?? this.principal(id).workspaceId,
-				goal: `${activation.goal}\nCurrent task contract (within the original authority): ${JSON.stringify(this.tasks.require(row.task_id).contract)}\nUser decisions: ${JSON.stringify(answers).slice(0, 8e3)}`,
+				goal: `${template.execution.instruction}\nUser goal: ${activation.goal}\nCurrent task contract (within the original authority): ${JSON.stringify(this.tasks.require(row.task_id).contract)}\nUser decisions: ${JSON.stringify(answers).slice(0, 8e3)}`,
 				instruction: input.instruction,
 				evidence,
 				capabilities: input.capabilities,
@@ -643,6 +681,25 @@ var TaskFollowUpService = class {
 						completionVerdict: "partial"
 					}
 				}).ok) throw new SceneConflictError("Task run changed before the result was recorded");
+				if (!this.scenes.finishAdapterRun(sceneRun, {
+					kind: "receipt",
+					summary: result.summary,
+					taskId: row.task_id,
+					taskRunId: runId,
+					sourceRevision: revision,
+					verification: { status: verification.passed ? "passed" : "unverified" },
+					remainingWork,
+					needsUser,
+					changes: resource ? [{
+						title: "Task workspace",
+						summary: `Resource: ${input.resource}; fingerprint: ${fingerprint}`,
+						uri: resource.rootPath
+					}] : [],
+					evidence: verification.output || verification.passed ? [{
+						title: "Approved verification",
+						summary: verification.output || "Exit code 0"
+					}] : []
+				}, Date.now())) throw new SceneConflictError("Scene run changed before the result was recorded");
 				this.db.prepare("UPDATE scene_task_bindings SET processed_revision = ?, continuation_requested = ? WHERE activation_id = ?").run(revision, continueAutomatically && !needsUser ? 1 : 0, id);
 				if (needsUser) this.runs.createWait({
 					taskId: row.task_id,
@@ -677,6 +734,7 @@ var TaskFollowUpService = class {
 					completionVerdict: "not_achieved"
 				}
 			});
+			this.scenes.failRun(sceneRun, Date.now(), changed ? "execution_cancelled" : "execution_failed");
 			if (!changed) this.fail(current, error instanceof Error ? error.message : "Task execution failed");
 		} finally {
 			clearInterval(heartbeat);
@@ -709,4 +767,4 @@ var TaskFollowUpService = class {
 	}
 };
 //#endregion
-export { TaskFollowUpService };
+export { SceneTaskExecutionService };

package/dist/src/scenes/templates.d.ts

@@ -18,7 +18,7 @@ export declare const mailFollowUpTemplate: {
         type: "schedule";
     })[];
     execution: {
-        kind: "agent";
+        kind: string;
         instruction: string;
         limits: {
             timeoutSeconds: number;
@@ -50,7 +50,7 @@ export declare const familyPlanTemplate: {
         type: "schedule";
     })[];
     execution: {
-        kind: "agent";
+        kind: string;
         instruction: string;
         limits: {
             timeoutSeconds: number;

package/dist/src/scenes/userNotes.d.ts

@@ -1,10 +1,13 @@
 import type { DatabaseSync } from 'node:sqlite';
 import type { SceneContextProvider, SceneEvidence } from './execution.js';
+import type { SceneActivation } from './contracts.js';
 /** Explicit notes belong to one delegation, not an implicit family-wide data grant. */
 export declare class SceneUserNotesProvider implements SceneContextProvider {
     private readonly db;
     private readonly clock;
     readonly id = "user_notes";
     constructor(db: DatabaseSync, clock?: () => number);
+    setupIssues(activation: SceneActivation): string[];
+    authorization(activation: SceneActivation): string[] | null;
     read(input: Parameters<SceneContextProvider['read']>[0]): Promise<SceneEvidence[]>;
 }

package/dist/src/scenes/userNotes.js

@@ -7,6 +7,12 @@ var SceneUserNotesProvider = class {
 		this.db = db;
 		this.clock = clock;
 	}
+	setupIssues(activation) {
+		return activation.scope.kind === "personal" ? [] : ["personal_notes_scope"];
+	}
+	authorization(activation) {
+		return activation.scope.kind === "personal" ? [] : null;
+	}
 	async read(input) {
 		input.signal.throwIfAborted();
 		if (!input.permissions.contextProviders.includes(this.id) || input.activation.scope.kind !== "personal") throw new Error("Personal notes permission is required");

package/dist/src/session/client-history.d.ts

@@ -14,6 +14,8 @@ export interface ClientHistoryMessage {
     timestamp?: number;
     /** Whitelisted display metadata; never includes source snapshot text. */
     metadata?: {
+        /** Stable client-generated id used to reconcile optimistic sends exactly. */
+        clientMessageId?: string;
         sourceContexts?: Array<{
             refId?: string;
             kind: 'note' | 'task' | 'file' | 'session' | 'browser_tab' | 'browser_page' | 'mcp_resource';
@@ -77,4 +79,5 @@ export declare function transcriptRowsToClientHistory(rows: TranscriptStoredRow[
     limit?: number;
     startRowNumber?: number;
     endRowNumber?: number;
+    rowNumberOffset?: number;
 }): ClientHistoryMessage[];

package/dist/src/session/client-history.js

@@ -8,9 +8,13 @@ init_src();
 function sourceContextDisplayMetadata(metadata) {
 	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return void 0;
 	const record = metadata;
+	const clientMessageId = typeof record.clientMessageId === "string" && record.clientMessageId.trim() ? record.clientMessageId : void 0;
 	const rows = record.sourceContexts;
 	const userTurnDocument = isUserTurnDocument(record.userTurnDocument) ? record.userTurnDocument : void 0;
-	if (!Array.isArray(rows)) return userTurnDocument ? { userTurnDocument } : void 0;
+	if (!Array.isArray(rows)) return clientMessageId || userTurnDocument ? {
+		...clientMessageId ? { clientMessageId } : {},
+		...userTurnDocument ? { userTurnDocument } : {}
+	} : void 0;
 	const sourceContexts = rows.flatMap((value) => {
 		if (!value || typeof value !== "object" || Array.isArray(value)) return [];
 		const row = value;
@@ -29,7 +33,8 @@ function sourceContextDisplayMetadata(metadata) {
 			...row.kind === "file" && (row.fileKind === "file" || row.fileKind === "directory") ? { fileKind: row.fileKind } : {}
 		}];
 	});
-	return sourceContexts.length || userTurnDocument ? {
+	return clientMessageId || sourceContexts.length || userTurnDocument ? {
+		...clientMessageId ? { clientMessageId } : {},
 		...sourceContexts.length ? { sourceContexts } : {},
 		...userTurnDocument ? { userTurnDocument } : {}
 	} : void 0;
@@ -367,9 +372,9 @@ function transcriptRowsToClientHistory(rows, opts) {
 	const out = [];
 	const reviewTraceToolById = /* @__PURE__ */ new Map();
 	for (const [offset, row] of slice.entries()) {
-		const rowNumber = startIndex + offset + 1;
-		const id = `row-${rowNumber}`;
-		const displayIndex = displayIndexByRowNumber.get(rowNumber);
+		const localRowNumber = startIndex + offset + 1;
+		const id = `row-${(opts?.rowNumberOffset ?? 0) + localRowNumber}`;
+		const displayIndex = displayIndexByRowNumber.get(localRowNumber);
 		if (isCompactionRow(row)) {
 			out.push({
 				id,

package/dist/src/session/manager.d.ts

@@ -43,6 +43,7 @@ export declare class SessionIndex extends EventEmitter {
             hasMore: boolean;
             before?: string;
             nextBeforeCursor?: string;
+            revision?: number;
         };
     } | null>;
     /**

package/dist/src/session/resolve-session.js

@@ -2,7 +2,8 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { requireXopcDatabase } from "../storage/sqlite/connection.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
-import { findConversationIdByTranscriptId, getSessionPersistedLevels } from "../storage/sqlite/session-repository.js";
+import { findConversationIdByTranscriptId } from "../storage/sqlite/session-repository.js";
+import { getSessionConfig } from "../storage/sqlite/config-repository.js";
 import { init_sqlite } from "../storage/sqlite/index.js";
 import { SessionConfigSchema, init_schema } from "../config/schema.js";
 import { normalizeThinkLevel, normalizeVerboseLevel } from "../agent/transcript/thinking-types.js";
@@ -69,8 +70,8 @@ async function resolveSession(opts) {
 		conversationId,
 		sessionMetadata,
 		isNewSession,
-		persistedThinking: fresh && conversationId ? normalizeThinkLevel(getSessionPersistedLevels(conversationId)?.thinkingLevel ?? void 0) : void 0,
-		persistedVerbose: fresh && conversationId ? normalizeVerboseLevel(getSessionPersistedLevels(conversationId)?.verboseLevel ?? void 0) : void 0
+		persistedThinking: fresh && conversationId ? normalizeThinkLevel(getSessionConfig(conversationId)?.thinkingLevel) : void 0,
+		persistedVerbose: fresh && conversationId ? normalizeVerboseLevel(getSessionConfig(conversationId)?.verboseLevel) : void 0
 	};
 }
 //#endregion

package/dist/src/session/session-title.js

@@ -170,7 +170,7 @@ Title:`,
 			maxTokens: 64,
 			temperature: .35,
 			signal
-		});
+		}, void 0, { operation: "session.generate_title" });
 		let text = "";
 		if (Array.isArray(result.content)) {
 			for (const c of result.content) if (c && typeof c === "object" && c.type === "text") text += String(c.text || "");

package/dist/src/session/store.d.ts

@@ -101,6 +101,7 @@ export declare class SessionStore {
             hasMore: boolean;
             before?: string;
             nextBeforeCursor?: string;
+            revision?: number;
         };
     } | null>;
     private buildSessionDetail;

package/dist/src/session/store.js

@@ -188,9 +188,9 @@ var SessionStore = class {
 				beforeIndex: hasBeforeCursor ? parsedBefore : void 0,
 				includeContext: true
 			});
-			const messages = transcriptRowsToClientHistory(page.rows);
 			const endIndex = hasBeforeCursor ? Math.min(page.total, Math.max(0, parsedBefore)) : Math.max(0, page.total - offset);
 			const startIndex = Math.max(0, endIndex - page.rows.length);
+			const messages = transcriptRowsToClientHistory(page.rows, { rowNumberOffset: startIndex });
 			const session = {
 				...metadata,
 				messages,
@@ -205,7 +205,8 @@ var SessionStore = class {
 					offset,
 					hasMore: hasBeforeCursor ? startIndex > 0 : offset + limit < page.total,
 					...hasBeforeCursor ? { before: String(endIndex) } : {},
-					...nextBeforeCursor ? { nextBeforeCursor } : {}
+					...nextBeforeCursor ? { nextBeforeCursor } : {},
+					revision: page.revision
 				}
 			};
 		}
@@ -793,7 +794,6 @@ var SessionStore = class {
 				customData: {
 					...sourceMetadata.customData ?? {},
 					...options.targetMetadata.customData ?? {},
-					genericNewChatShell: false,
 					forkedFromConversationId: sourceKey,
 					forkedFromTranscriptId: sourceMetadata.transcriptId,
 					forkedFromSessionName: sourceMetadata.name,

package/dist/src/storage/sqlite/ai-usage-repository.d.ts

@@ -0,0 +1,137 @@
+import type { AiUsageEvent, AiUsageFinish } from '../../usage/types.js';
+export declare const AI_USAGE_RETENTION_MS: number;
+export declare function insertAiUsageEvent(event: AiUsageEvent): void;
+export declare function finishAiUsageEvent(id: string, finish: AiUsageFinish & {
+    estimatedCostMicrousd?: number;
+}): void;
+export declare function markStaleAiUsageEventsUnknown(cutoffMs: number, now?: number): number;
+export declare function pruneAiUsageEvents(cutoffMs: number): number;
+export declare function getAiUsageEvent(id: string): Record<string, unknown> | undefined;
+export type AiUsageQuery = {
+    from: number;
+    to: number;
+    category?: string;
+    provider?: string;
+    model?: string;
+    agentId?: string;
+    conversationId?: string;
+};
+export type AiUsageTotals = {
+    calls: number;
+    succeededCalls: number;
+    failedCalls: number;
+    unknownCostCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    knownCostUsd: string;
+    costCompleteness: 'complete' | 'partial' | 'unknown';
+};
+export declare function summarizeAiUsage(query: AiUsageQuery): {
+    totals: AiUsageTotals;
+    byCategory: Array<{
+        key: string;
+        totals: AiUsageTotals;
+    }>;
+    byModel: Array<{
+        key: string;
+        provider: string;
+        model: string;
+        totals: AiUsageTotals;
+    }>;
+};
+export declare function listAiUsageEvents(query: AiUsageQuery & {
+    limit?: number;
+    before?: {
+        startedAt: number;
+        id: string;
+    };
+}): {
+    items: {
+        id: string;
+        traceId: string;
+        parentEventId: string;
+        conversationId: string;
+        runId: string;
+        agentId: string;
+        category: string;
+        operation: string;
+        trigger: string;
+        reasonKey: string;
+        provider: string;
+        model: string;
+        status: string;
+        startedAt: number;
+        finishedAt: number;
+        durationMs: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens: number;
+        totalTokens: number;
+        estimatedCostUsd: string;
+        costSource: string;
+        pricingSnapshot: Record<string, number>;
+        errorSummary: string;
+    }[];
+    nextCursor: string;
+};
+export declare function getAiUsageEventView(id: string): {
+    id: string;
+    traceId: string;
+    parentEventId: string;
+    conversationId: string;
+    runId: string;
+    agentId: string;
+    category: string;
+    operation: string;
+    trigger: string;
+    reasonKey: string;
+    provider: string;
+    model: string;
+    status: string;
+    startedAt: number;
+    finishedAt: number;
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: string;
+    costSource: string;
+    pricingSnapshot: Record<string, number>;
+    errorSummary: string;
+};
+export declare function listAiUsageTrace(traceId: string): {
+    id: string;
+    traceId: string;
+    parentEventId: string;
+    conversationId: string;
+    runId: string;
+    agentId: string;
+    category: string;
+    operation: string;
+    trigger: string;
+    reasonKey: string;
+    provider: string;
+    model: string;
+    status: string;
+    startedAt: number;
+    finishedAt: number;
+    durationMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    totalTokens: number;
+    estimatedCostUsd: string;
+    costSource: string;
+    pricingSnapshot: Record<string, number>;
+    errorSummary: string;
+}[];