@comma-agents/core 2.0.0-rc.0

package/dist/hooks/built-in/token-tracking/token-tracking.types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Metadata about a model's token limits.
+ *
+ * Used to compute context budget estimates (percentage used, remaining tokens).
+ * If context window information is unavailable, budget-related fields on
+ * `TokenSnapshot` will be `undefined`.
+ */
+export interface ModelMetadata {
+    /** Total context window size in tokens. */
+    readonly contextWindow: number;
+    /** Maximum output tokens the model can generate per response. */
+    readonly maxOutputTokens?: number;
+}
+/**
+ * Configuration for creating a TokenTracker.
+ */
+export interface TokenTrackerConfig {
+    /**
+     * Model identifier in `"providerID/modelID"` format (e.g., `"openai/gpt-4o"`).
+     * Used to look up context window metadata from the built-in model catalog.
+     */
+    readonly model?: string;
+    /**
+     * Explicit model metadata. When provided, overrides the built-in catalog lookup.
+     * Use this for models not in the catalog, or to override catalog values.
+     */
+    readonly modelMetadata?: ModelMetadata;
+}
+/**
+ * A single recorded call's token usage, captured from the `afterCallResult` hook.
+ */
+export interface TokenUsageRecord {
+    /** Number of prompt (input) tokens for this call. */
+    readonly promptTokens: number;
+    /** Number of completion (output) tokens for this call. */
+    readonly completionTokens: number;
+    /** Total tokens for this call (`promptTokens + completionTokens`). */
+    readonly totalTokens: number;
+    /** Timestamp of when this usage was recorded. */
+    readonly timestamp: number;
+}
+/**
+ * A point-in-time snapshot of the tracker's accumulated state.
+ *
+ * All token counts are real values reported by the provider (post-call),
+ * not estimates. Context budget fields are present only when model metadata
+ * (context window size) is available.
+ */
+export interface TokenSnapshot {
+    /** Total prompt tokens across all recorded calls. */
+    readonly totalPromptTokens: number;
+    /** Total completion tokens across all recorded calls. */
+    readonly totalCompletionTokens: number;
+    /** Total tokens across all recorded calls. */
+    readonly totalTokens: number;
+    /** Number of calls recorded so far. */
+    readonly callCount: number;
+    /**
+     * The most recent call's prompt token count.
+     * This represents the current context window usage for the last call —
+     * the best indicator of how full the context window is right now.
+     * `undefined` if no calls have been recorded.
+     */
+    readonly lastPromptTokens: number | undefined;
+    /**
+     * Context window size in tokens, if model metadata is available.
+     * `undefined` when no model metadata was provided or found in the catalog.
+     */
+    readonly contextWindow: number | undefined;
+    /**
+     * Maximum output tokens per response, if model metadata is available.
+     * `undefined` when not specified in metadata.
+     */
+    readonly maxOutputTokens: number | undefined;
+    /**
+     * Percentage of the context window used by the most recent call's prompt.
+     * Value between 0 and 1 (e.g., 0.75 = 75% used).
+     * `undefined` when context window or last prompt token count is unavailable.
+     */
+    readonly contextUsagePercent: number | undefined;
+    /**
+     * Estimated tokens remaining in the context window based on the most
+     * recent call's prompt token count.
+     * `undefined` when context window or last prompt token count is unavailable.
+     */
+    readonly contextRemaining: number | undefined;
+    /** Individual call records in chronological order. */
+    readonly calls: readonly TokenUsageRecord[];
+}
+/**
+ * A mutable token usage tracker. Accumulates real token usage from
+ * `afterCallResult` hooks and provides queryable snapshots.
+ *
+ * Created via `createTokenTracker()` and attached to agents via `useTokenTracking()`.
+ *
+ * @example
+ * ```ts
+ * import { useTokenTracking } from "@comma-agents/core";
+ *
+ * const tracker = useTokenTracking(agent, { model: "openai/gpt-4o" });
+ *
+ * await agent.call("Hello");
+ * const snapshot = tracker.snapshot();
+ * console.log(`Used ${snapshot.totalTokens} tokens`);
+ * console.log(`Context ${(snapshot.contextUsagePercent! * 100).toFixed(1)}% full`);
+ * ```
+ */
+export interface TokenTracker {
+    /**
+     * Record a call's token usage. Called automatically by the `afterCallResult`
+     * hook installed by `useTokenTracking()`.
+     */
+    record(promptTokens: number, completionTokens: number): void;
+    /** Take a snapshot of accumulated usage. */
+    snapshot(): TokenSnapshot;
+    /** Clear all recorded usage data. */
+    reset(): void;
+}
+/**
+ * Configuration for `useTokenTracking()`.
+ *
+ * All fields are optional — when omitted, the model is auto-detected from
+ * the agent's config and looked up in the built-in catalog.
+ */
+export interface UseTokenTrackingConfig {
+    /**
+     * Explicit model identifier in `"providerID/modelID"` format.
+     * Overrides auto-detection from the agent's config.
+     */
+    readonly model?: string;
+    /**
+     * Explicit model metadata. When provided, overrides both auto-detection
+     * and catalog lookup. Use this for models not in the catalog.
+     */
+    readonly modelMetadata?: ModelMetadata;
+}

package/dist/hooks/hooks.d.ts

@@ -0,0 +1,10 @@
+import type { SideEffectHook, TransformHook } from "./hooks.types";
+/**
+ * Execute an array of side-effect hooks in order.
+ */
+export declare function runSideEffectHooks<HookValue>(hooks: ReadonlyArray<SideEffectHook<HookValue>> | undefined, value: HookValue): Promise<void>;
+/**
+ * Execute an array of transform hooks in order, chaining outputs.
+ * Returns the final transformed value.
+ */
+export declare function runTransformHooks<HookValue>(hooks: ReadonlyArray<TransformHook<HookValue>> | undefined, value: HookValue): Promise<HookValue>;

package/dist/hooks/hooks.types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A side-effect hook that receives context but does not transform values.
+ * Used for logging, metrics, state management, etc.
+ */
+export type SideEffectHook<HookValue> = (value: HookValue) => void | Promise<void>;
+/**
+ * A transform hook that receives a value and returns a (possibly modified) value.
+ * Used for altering messages, responses, etc. The output of one hook becomes
+ * the input of the next (chained).
+ */
+export type TransformHook<HookValue> = (value: HookValue) => HookValue | Promise<HookValue>;

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { runSideEffectHooks, runTransformHooks } from "./hooks";
+export type { SideEffectHook, TransformHook } from "./hooks.types";

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+export type { AbortableAsyncGenerator, AbortablePromise, } from "./abortable";
+export { createAbortableGenerator, createAbortablePromise, } from "./abortable";
+export { createAgent } from "./agents/agent/agent";
+export type { Agent, AgentCallResult, AgentConfig, AgentOutputSchema, AgentStreamEvent, ModelOptions, } from "./agents/agent/agent.types";
+export { createUserAgent } from "./agents/built-in/user/user-agent";
+export type { InputCollector, InputRequest, UserAgentConfig, } from "./agents/built-in/user/user-agent.types";
+export { hookIntoAgent } from "./agents/hook-into-agent/hook-into-agent";
+export type { AgentHooks, ToolHooks } from "./agents/hooks/hooks.types";
+export type { AgentDescription, LoadAgentOptions } from "./agents/loader/index";
+export { AgentDescriptionSchema, loadAgent, loadAgentFromString, } from "./agents/loader/index";
+export type { AssistantModelMessage, CompactionOptions, ContextPrepareInput, ContextUsage, ContextRecordTransform, ContextRetentionOptions, ContextTransformInput, ConversationHistory, ConversationRecord, ConversationRecordStatus, ConversationRetentionEvent, ConversationUsage, CreateConversationRecordInput, ModelMessage, ResponseMessage, RollingWindowOptions, SummarizeRecords, ToolModelMessage, UserModelMessage, } from "./conversation-context";
+export type { ConversationContext, ConversationContextOptions, } from "./conversation-context/index";
+export { applyCompaction, applyRollingWindow, contextUsageFromSteps, createConversationContext, createConversationRecord, parseConversationJson, parseConversationJsonl, parseConversationYaml, prepareContextRecords, recordsToMessages, recordToJsonlLine, serializeConversationRecordsJson, serializeConversationRecords, serializeConversationRecordsYaml, } from "./conversation-context/index";
+export type { ApiCredential, AuthStatus, CreateCredentialStoreOptions, Credential, CredentialBackend, CredentialStore, CredentialStoreData, CustomCredential, EnvVarMap, OAuthCredential, } from "./credentials/index";
+export { ApiCredentialSchema, CredentialSchema, CustomCredentialSchema, createCredentialStore, createJsonFileBackend, OAuthCredentialSchema, resolveCredentialsPath, resolveDataDir, } from "./credentials/index";
+export type { GlobalDefaults, ProviderRegistration } from "./defaults/index";
+export { getGlobalCredentialStore, getGlobalDefaults, getGlobalProviderResolver, registerProvider, resetGlobalDefaults, setGlobalCredentialStore, setProviderCacheDir, unregisterProvider, } from "./defaults/index";
+export { AgentCallError, CommaAgentsError, FlowExecutionError, HookExecutionError, ModelResolutionError, SandboxViolationError, StrategyValidationError, ToolExecutionError, } from "./errors/index";
+export type { BroadcastFlowConfig, CustomFlowConfig, CycleFlowConfig, CycleHooks, FlowConfig, FlowContext, FlowExecutor, FlowHooks, FlowResult, } from "./flows/index";
+export { buildFlowAgent, createBroadcastFlow, createCycleFlow, createFlow, createSequentialFlow, hookIntoFlow, } from "./flows/index";
+export type { FlowDescription, LoadFlowOptions } from "./flows/loader/index";
+export { FlowDescriptionSchema, loadFlow, loadFlowFromString, } from "./flows/loader/index";
+export type { AccessRequest, AccessType, Guard, GuardCallbacks, GuardPermissionRequest, GuardPolicySnapshot, Policy, PolicyDecision, } from "./guard/index";
+export { approveCommandsPolicy, buildDefaultPolicies, createGuard, denyCommandsPolicy, forbiddenGlobsPolicy, pathPolicy, } from "./guard/index";
+export type { SideEffectHook, TransformHook } from "./hooks";
+export { runSideEffectHooks, runTransformHooks } from "./hooks";
+export type { ModelMetadata, TokenSnapshot, TokenTracker, TokenTrackerConfig, TokenUsageRecord, UseTokenTrackingConfig, } from "./hooks/built-in/token-tracking/index";
+export { createTokenTracker, useTokenTracking, } from "./hooks/built-in/token-tracking/index";
+export type { LanguageDiagnostic, LanguageDiagnosticSeverity, LanguageHoverResult, LanguageLocation, LanguagePosition, LanguageRange, LanguageService, LanguageSymbol, LspMethod, LspRequest, LspResponse, } from "./language/index";
+export type { CatalogData, CatalogModel, CatalogProvider, ListModelsContext, ListModelsFn, ListModelsResult, Modality, ModelCapabilities, ModelCost, ModelInfo, ModelModalities, ModelStatus, ModelsSource, ParsedModel, ProviderDefinition, ProviderFactory, ProviderInfo, ProviderResolver, ProviderWithModels, } from "./model/index";
+export { extractProviderIds, getCatalogModels, getCatalogProvider, getCatalogProviderSync, getCatalogSnapshot, getModelCapabilities, getModelMetadata, getQualifiedModelMetadata, getProviderDefinition, getProviderInfo, getProviderPackage, getProvidersForModel, getReverseModelIndex, isKnownProvider, listAllProviderModels, listCatalogProviders, listProviderDefinitions, listProviderModels, listProviders, loadCatalog, parseModel, refreshCatalog, registerModel, registerProviderDefinition, resetCatalog, resetModelRegistry, resetProviderRegistry, resolveCatalogCachePath, resolveModel, toModelInfo, unregisterModel, unregisterProviderDefinition, } from "./model/index";
+export type { BuildMessagesOptions, PromptTemplate, PromptTemplateConfig, SystemPromptOptions, TemplateValue, TemplateVariables, } from "./prompts/index";
+export { buildMessages, createPromptTemplate, resolveSystemPrompt, } from "./prompts/index";
+export type { AccessMode, PathPolicy, PermissionDecision, PermissionOperation, PermissionRequest, PermissionRequester, PolicyPatch, Sandbox, SandboxConfig, } from "./sandbox/index";
+export { createSandbox, DEFAULT_DAEMON_SANDBOX_CONFIG, DEFAULT_FORBIDDEN_GLOBS, DEFAULT_SANDBOX_CONFIG, getSandbox, inSandbox, PERMISSIVE_SANDBOX_CONFIG, } from "./sandbox/index";
+export type { LoadSkillsOptions, Skill, SkillLoadResult, SkillLoadWarning, SkillMetadata, SkillRegistry, } from "./skills/index";
+export { buildSkillsPromptHeader, createSkillRegistry, loadSkills, } from "./skills/index";
+export type { AgentDef, AgentStep, BroadcastFlowDef, BuiltInToolName, CommaProjectManifest, CycleFlowDef, DiscoveredStrategy, DiscoveredStrategyOrigin, DiscoverStrategiesOptions, DiscoverStrategiesResult, DiscoveryWarning, ExportStrategyOptions, FlowDef, LLMAgentDef, LoadedProject, LoadedStrategy, LoadStrategyOptions, SequentialFlowDef, Strategy, UserAgentDef, } from "./strategy/index";
+export { CommaProjectManifestSchema, discoverStrategies, exportStrategy, isAgentStep, isFlowDef, isLLMAgentDef, isUserAgentDef, loadProject, loadStrategy, loadStrategyFromString, readStrategyFile, StrategySchema, } from "./strategy/index";
+export type { ProjectedConversationContext, Timeline, TimelineEvent, TimelineFilter, } from "./timeline/index";
+export { createTimeline, projectConversationContext, projectFileState, } from "./timeline/index";
+export { buildToolSystemPrompt, mergeSystemPrompts, } from "./tools/build-tool-system-prompt";
+export type { LspRequestData } from "./tools/built-in/lsp-request";
+export { defineTool } from "./tools/define/define-tool";
+export type { AuditEntry, AuditOperation, AuditSink, FileAuditSinkOptions, NewlineStyle, SessionFileEntry, SessionFileState, TrashEntry, TrashMetadata, UnifiedDiffOptions, WriteAtomicOptions, } from "./tools/io";
+export { applyBom, applyNewline, BINARY_DETECTION_SAMPLE_BYTES, BOM, buildSessionFileState, clearTrash, createFileAuditSink, createMemoryAuditSink, detectNewline, hasBom, isLikelyBinary, listTrash, moveToTrash, restoreFromTrash, STALE_FILE_RECOVERY_HINT, sha256OfBuffer, sha256OfFile, stripBom, toLF, trashWorkspaceDir, unifiedDiff, verifySessionFileState, writeAtomic, } from "./tools/io";
+export type { LaunchStrategyHandle, LaunchStrategyRequest, LaunchStrategyResult, } from "./tools/launch-strategy.types";
+export { errorResult, okResult, toolError } from "./tools/result";
+export { getRegisteredToolNames, registerTool, resetToolRegistry, resolveTools, unregisterTool, } from "./tools/tool.registry";
+export type { ToolContext, ToolDefinition as ToolDef, ToolError, ToolErrorKind, ToolResult, } from "./tools/tool.types";