@comma-agents/core 2.0.0-rc.0

package/dist/conversation-context/conversation-context.types.d.ts

@@ -0,0 +1,111 @@
+import type { AssistantModelMessage, ModelMessage, ToolModelMessage, UserModelMessage } from "ai";
+import type { ContextPrepareInput, ContextRetentionOptions, ConversationRetentionEvent } from "./retention/retention.types";
+export type { AssistantModelMessage, ModelMessage, ToolModelMessage, UserModelMessage, } from "ai";
+export type { CompactionOptions, ContextPrepareInput, ContextRecordTransform, ContextRetentionOptions, ContextTransformInput, ConversationRetentionEvent, RollingWindowOptions, SummarizeRecords, } from "./retention/retention.types";
+export type ResponseMessage = AssistantModelMessage | ToolModelMessage;
+/**
+ * Whether a record is part of the agent's effective (LLM-visible) context.
+ * `superseded` records are retained for export/audit but excluded from the
+ * message projection.
+ */
+export type ConversationRecordStatus = "active" | "superseded";
+export interface ConversationUsage {
+    /** Tokens used by the prompt/input side of the agent call. */
+    readonly promptTokens: number;
+    /** Tokens generated by the model output side of the agent call. */
+    readonly completionTokens: number;
+}
+export interface ContextUsage {
+    /** Tokens occupying the final model step's context window. */
+    readonly totalTokens: number;
+    /** Input tokens in the final model step, when reported. */
+    readonly inputTokens?: number;
+    /** Output tokens in the final model step, when reported. */
+    readonly outputTokens?: number;
+    /** Detailed input-token categories reported by the model provider. */
+    readonly inputTokenDetails?: {
+        readonly noCacheTokens?: number;
+        readonly cacheReadTokens?: number;
+        readonly cacheWriteTokens?: number;
+    };
+    /** Detailed output-token categories reported by the model provider. */
+    readonly outputTokenDetails?: {
+        readonly textTokens?: number;
+        readonly reasoningTokens?: number;
+    };
+}
+export interface ConversationRecord {
+    /** Stable identifier for this single agent call record. */
+    readonly id: string;
+    /** Agent that owns this context record. */
+    readonly agentName: string;
+    /** ISO timestamp for when the record was created. */
+    readonly createdAt: string;
+    /** User message sent to the agent for this call. */
+    readonly userMessage: UserModelMessage;
+    /** Assistant and tool messages returned by the AI SDK for this call. */
+    readonly responseMessages: readonly ResponseMessage[];
+    /** Final text returned by the agent. */
+    readonly text: string;
+    /** Exact token usage reported by the provider for this call. */
+    readonly usage: ConversationUsage;
+    /** Final model-step context usage. */
+    readonly contextUsage?: ContextUsage;
+    /** Provider finish reason for this call. */
+    readonly finishReason: string;
+    /**
+     * Whether this record feeds the agent's effective context.
+     * @default "active"
+     */
+    readonly status?: ConversationRecordStatus;
+    /** Id of the summary record that replaced this one, when superseded. */
+    readonly supersededBy?: string;
+}
+export interface CreateConversationRecordInput {
+    /** Stable identifier for this record. Defaults to a random UUID. */
+    readonly id?: string;
+    /** Agent that owns this context record. */
+    readonly agentName: string;
+    /** Creation timestamp. Defaults to the current time. */
+    readonly createdAt?: string;
+    /** User input sent to the agent. */
+    readonly userMessage: string | UserModelMessage;
+    /** Assistant and tool messages returned by the AI SDK for this call. */
+    readonly responseMessages: readonly ResponseMessage[];
+    /** Final text returned by the agent. */
+    readonly text: string;
+    /** Exact token usage reported by the provider for this call. */
+    readonly usage: ConversationUsage;
+    /** Final model-step context usage. */
+    readonly contextUsage?: ContextUsage;
+    /** Provider finish reason for this call. */
+    readonly finishReason: string;
+}
+export interface ConversationHistory {
+    /** Ordered conversation records across the run. */
+    readonly records: readonly ConversationRecord[];
+    /** Retention events that changed the effective model context. */
+    readonly retentionEvents: readonly ConversationRetentionEvent[];
+}
+/** Options for {@link createConversationContext}. */
+export interface ConversationContextOptions extends ContextRetentionOptions {
+}
+export interface ConversationContext {
+    readonly length: number;
+    readonly isEmpty: boolean;
+    appendRecord(record: ConversationRecord): void;
+    records(agentName?: string): readonly ConversationRecord[];
+    messages(agentName?: string): readonly ModelMessage[];
+    /** Prepare records before a model call by applying configured retention. */
+    prepareForCall(input: ContextPrepareInput): Promise<readonly ConversationRetentionEvent[]>;
+    importRecords(records: readonly ConversationRecord[]): void;
+    exportRecords(): readonly ConversationRecord[];
+    importJsonl(jsonl: string): void;
+    exportJsonl(): string;
+    importJson(json: string): void;
+    exportJson(): string;
+    importYaml(yaml: string): void;
+    exportYaml(): string;
+    clear(): void;
+    [Symbol.iterator](): Iterator<ConversationRecord>;
+}

package/dist/conversation-context/conversation-context.utils.d.ts

@@ -0,0 +1,6 @@
+import type { UserModelMessage } from "ai";
+import type { ConversationRecord } from "./conversation-context.types";
+/** Wrap plain text in the AI SDK user-message shape. */
+export declare function toUserMessage(text: string | UserModelMessage): UserModelMessage;
+/** Check the minimal public record fields expected by the context contract. */
+export declare function isConversationRecord(value: unknown): value is ConversationRecord;

package/dist/conversation-context/index.d.ts

@@ -0,0 +1,3 @@
+export { contextUsageFromSteps, createConversationContext, createConversationRecord, parseConversationJson, parseConversationJsonl, parseConversationYaml, recordsToMessages, recordToJsonlLine, serializeConversationRecords, serializeConversationRecordsJson, serializeConversationRecordsYaml, } from "./conversation-context";
+export type { AssistantModelMessage, CompactionOptions, ContextPrepareInput, ContextRecordTransform, ContextRetentionOptions, ContextTransformInput, ContextUsage, ConversationContext, ConversationContextOptions, ConversationHistory, ConversationRecord, ConversationRecordStatus, ConversationRetentionEvent, ConversationUsage, CreateConversationRecordInput, ModelMessage, ResponseMessage, RollingWindowOptions, SummarizeRecords, ToolModelMessage, UserModelMessage, } from "./conversation-context.types";
+export { applyCompaction, applyRollingWindow, prepareContextRecords, } from "./retention";

package/dist/conversation-context/retention/compaction/compaction.constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_COMPACTION_KEEP_RECENT = 8;
+export declare const DEFAULT_COMPACTION_THRESHOLD_RATIO = 0.85;
+export declare const COMPACTION_SUMMARY_REQUEST = "[Earlier conversation compacted - summary follows.]";

package/dist/conversation-context/retention/compaction/compaction.d.ts

@@ -0,0 +1,21 @@
+import type { ConversationRecord } from "../../conversation-context.types";
+import type { ConversationRetentionEvent } from "../retention.types";
+import type { ApplyCompactionInput } from "./compaction.types";
+/**
+ * Compact older active records into one summary record.
+ *
+ * @param input - Full retained record history, options, agent name, and trigger metadata.
+ * @example
+ * ```ts
+ * const result = await applyCompaction({
+ *   records,
+ *   options: { keepRecent: 8, summarize },
+ *   agentName: "assistant",
+ *   trigger: { contextUsage: { totalTokens: 90_000 }, tokenLimit: 100_000 },
+ * });
+ * ```
+ */
+export declare function applyCompaction(input: ApplyCompactionInput): Promise<{
+    readonly records: readonly ConversationRecord[];
+    readonly event?: ConversationRetentionEvent;
+}>;

package/dist/conversation-context/retention/compaction/compaction.types.d.ts

@@ -0,0 +1,26 @@
+import type { ConversationRecord } from "../../conversation-context.types";
+import type { ConversationRetentionTrigger } from "../retention.types";
+/** Summarize a span of records into a single plain-text summary. */
+export type SummarizeRecords = (records: readonly ConversationRecord[]) => Promise<string>;
+/** Configuration for compacting older records into one summary record. */
+export interface CompactionOptions {
+    /** Number of most-recent active records kept verbatim. @default 8 */
+    readonly keepRecent?: number;
+    /** Active-record count that triggers compaction. @default keepRecent * 2 */
+    readonly threshold?: number;
+    /** Context usage ratio that triggers compaction. @default 0.85 */
+    readonly thresholdRatio?: number;
+    /** Summarizer used to fold older records into one summary. */
+    readonly summarize?: SummarizeRecords;
+}
+/** Input for applying compaction to full retained record history. */
+export interface ApplyCompactionInput {
+    /** Full retained record history. */
+    readonly records: readonly ConversationRecord[];
+    /** Compaction configuration and summarizer. */
+    readonly options: CompactionOptions;
+    /** Agent that owns the synthetic summary record. */
+    readonly agentName: string;
+    /** Metadata used to decide whether compaction should run. */
+    readonly trigger: ConversationRetentionTrigger;
+}

package/dist/conversation-context/retention/compaction/index.d.ts

@@ -0,0 +1,2 @@
+export { applyCompaction } from "./compaction";
+export type { CompactionOptions, SummarizeRecords } from "./compaction.types";

package/dist/conversation-context/retention/index.d.ts

@@ -0,0 +1,4 @@
+export { applyCompaction } from "./compaction";
+export { prepareContextRecords } from "./retention";
+export type { CompactionOptions, ContextPrepareInput, ContextRecordTransform, ContextRetentionOptions, ContextRetentionResult, ContextTransformInput, ConversationRetentionEvent, ConversationRetentionTrigger, RollingWindowOptions, SummarizeRecords, } from "./retention.types";
+export { applyRollingWindow } from "./rolling-window";

package/dist/conversation-context/retention/retention.d.ts

@@ -0,0 +1,9 @@
+import type { ContextRetentionOptions, ContextRetentionResult, ContextTransformInput } from "./retention.types";
+/**
+ * Prepare conversation records before an agent call by applying built-in
+ * retention options and any custom transforms.
+ *
+ * @param options - Context retention and transform options.
+ * @param input - Current records plus the owning agent name.
+ */
+export declare function prepareContextRecords(options: ContextRetentionOptions, input: ContextTransformInput): Promise<ContextRetentionResult>;

package/dist/conversation-context/retention/retention.types.d.ts

@@ -0,0 +1,90 @@
+import type { ContextUsage, ConversationRecord } from "../conversation-context.types";
+import type { CompactionOptions } from "./compaction";
+import type { RollingWindowOptions } from "./rolling-window";
+export type { CompactionOptions, SummarizeRecords } from "./compaction";
+export type { RollingWindowOptions } from "./rolling-window";
+/** Input used when preparing records for an agent call. */
+export interface ContextPrepareInput {
+    readonly agentName: string;
+    readonly model?: string;
+    readonly contextUsage?: ContextUsage;
+    readonly contextWindow?: number;
+    readonly maxInputTokens?: number;
+}
+/** Input handed to a custom record transform. */
+export interface ContextTransformInput extends ContextPrepareInput {
+    readonly records: readonly ConversationRecord[];
+}
+/** Custom record transform used for behavior beyond built-in retention. */
+export type ContextRecordTransform = (input: ContextTransformInput) => readonly ConversationRecord[] | Promise<readonly ConversationRecord[]>;
+/** Metadata explaining why retention ran for an agent context. */
+export interface ConversationRetentionTrigger {
+    /** Provider/model identifier involved in the retention decision. */
+    readonly model?: string;
+    /** Final-step context usage from the previous model call. */
+    readonly contextUsage?: ContextUsage;
+    /** Token limit used for the threshold comparison. */
+    readonly tokenLimit?: number;
+    /** Provider context window, when known. */
+    readonly contextWindow?: number;
+    /** Provider max input tokens, when known. */
+    readonly maxInputTokens?: number;
+    /** Observed `contextUsage.totalTokens / tokenLimit`, when token metadata is known. */
+    readonly ratio?: number;
+    /** Ratio threshold that triggers default compaction. */
+    readonly thresholdRatio?: number;
+    /** Active record count that triggered explicit count-based compaction. */
+    readonly activeRecordCount?: number;
+    /** Configured active-record threshold for explicit count-based compaction. */
+    readonly recordThreshold?: number;
+}
+/** Event emitted when retention changes an agent's effective context. */
+export interface ConversationRetentionEvent {
+    /** Stable identifier for this retention event. */
+    readonly id: string;
+    /** Agent whose context was changed. */
+    readonly agentName: string;
+    /** ISO timestamp for when retention ran. */
+    readonly createdAt: string;
+    /** Retention operation that ran. */
+    readonly kind: "compaction";
+    /** Why the operation was triggered. */
+    readonly reason: "context-window" | "record-count";
+    /** Trigger metadata used to decide whether retention should run. */
+    readonly trigger: ConversationRetentionTrigger;
+    /** Number of active records compacted into the summary. */
+    readonly recordsCompacted: number;
+    /** Number of recent active records retained verbatim. */
+    readonly recordsRetained: number;
+    /** Synthetic summary record inserted into the active context. */
+    readonly summaryRecord: ConversationRecord;
+    /** Ids of records tombstoned by this retention event. */
+    readonly supersededRecordIds: readonly string[];
+    /** Existing active record before which the summary was inserted. */
+    readonly insertBeforeRecordId?: string;
+}
+/** Result of applying configured context retention. */
+export interface ContextRetentionResult {
+    /** Updated full record list, including tombstoned records. */
+    readonly records: readonly ConversationRecord[];
+    /** Retention events emitted while preparing the context. */
+    readonly events: readonly ConversationRetentionEvent[];
+}
+/** Retention and compaction options for a conversation context. */
+export interface ContextRetentionOptions {
+    /**
+     * Keep only the most recent active records visible to the model. A number is
+     * shorthand for `{ maxRecords: number }`.
+     */
+    readonly rollingWindow?: number | RollingWindowOptions;
+    /**
+     * Compact older active records into a summary. `true` enables default
+     * thresholds; an object customizes them.
+     */
+    readonly compaction?: boolean | CompactionOptions;
+    /**
+     * Optional programmatic extension point that runs after built-in rolling and
+     * compaction behavior.
+     */
+    readonly transformRecords?: ContextRecordTransform | readonly ContextRecordTransform[];
+}

package/dist/conversation-context/retention/retention.utils.d.ts

@@ -0,0 +1,3 @@
+import type { ConversationRecord } from "../conversation-context.types";
+/** Records that are still part of the agent's effective (LLM-visible) context. */
+export declare function activeRecords(records: readonly ConversationRecord[]): readonly ConversationRecord[];

package/dist/conversation-context/retention/rolling-window/index.d.ts

@@ -0,0 +1,2 @@
+export { applyRollingWindow } from "./rolling-window";
+export type { RollingWindowOptions } from "./rolling-window.types";

package/dist/conversation-context/retention/rolling-window/rolling-window.d.ts

@@ -0,0 +1,13 @@
+import type { ConversationRecord } from "../../conversation-context.types";
+import type { RollingWindowOptions } from "./rolling-window.types";
+/**
+ * Apply a rolling active-record window without deleting exported records.
+ *
+ * @param records - Full retained record history.
+ * @param options - Rolling-window configuration.
+ * @example
+ * ```ts
+ * const prepared = applyRollingWindow(records, { maxRecords: 40 });
+ * ```
+ */
+export declare function applyRollingWindow(records: readonly ConversationRecord[], options: RollingWindowOptions): readonly ConversationRecord[];

package/dist/conversation-context/retention/rolling-window/rolling-window.types.d.ts

@@ -0,0 +1,5 @@
+/** Configuration for rolling active records out of the LLM-visible context. */
+export interface RollingWindowOptions {
+    /** Maximum active records kept visible to the model. */
+    readonly maxRecords: number;
+}

package/dist/credentials/backends/json-file.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialBackend } from "../credentials.types";
+export interface JsonFileBackendOptions {
+    /** Absolute path to the credentials JSON file. */
+    readonly filePath: string;
+}
+/**
+ * Creates a JSON file-backed credential storage backend.
+ *
+ * - Creates parent directories on first write.
+ * - Sets file permissions to 0o600 (owner read/write only).
+ * - Returns empty data when the file doesn't exist.
+ * - Returns empty data when the file contains invalid JSON or fails
+ *   schema validation (logs a warning but doesn't throw).
+ *
+ * @example
+ * ```ts
+ * const backend = createJsonFileBackend({ filePath: "/home/user/.config/credentials.json" });
+ * const data = await backend.readAll();
+ * ```
+ */
+export declare function createJsonFileBackend(options: JsonFileBackendOptions): CredentialBackend;

package/dist/credentials/credentials.constants.d.ts

@@ -0,0 +1,9 @@
+import type { EnvVarMap } from "./credentials.types";
+/**
+ * Well-known environment variable names for common AI providers.
+ *
+ * This is intentionally a subset — strategies can specify custom
+ * env var names via the strategy schema, and users can extend
+ * this map via configuration.
+ */
+export declare const WELL_KNOWN_ENV_VARS: EnvVarMap;

package/dist/credentials/credentials.d.ts

@@ -0,0 +1,18 @@
+import type { CreateCredentialStoreOptions, CredentialStore } from "./credentials.types";
+/**
+ * Create a credential store backed by the given storage backend.
+ *
+ * The store provides layered credential resolution:
+ * 1. Strategy-scoped credential (if `scope` is a strategy name, not `"$global"`)
+ * 2. Environment variable (well-known + custom mappings)
+ * 3. Global-scoped credential (`"$global"`)
+ *
+ * @example
+ * ```ts
+ * const store = createCredentialStore({
+ *   backend: createJsonFileBackend({ filePath: "/path/to/credentials.json" }),
+ * });
+ * const credential = await store.resolve("openai", "my-strategy");
+ * ```
+ */
+export declare function createCredentialStore(options: CreateCredentialStoreOptions): CredentialStore;

package/dist/credentials/credentials.schema.d.ts

@@ -0,0 +1,102 @@
+import { z } from "zod";
+/** API key credential — simple secret string. */
+export declare const ApiCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"api">;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "api";
+    key: string;
+}, {
+    type: "api";
+    key: string;
+}>;
+/** OAuth 2.0 credential — access + refresh tokens with expiry. */
+export declare const OAuthCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    /** ISO-8601 datetime when the access token expires. */
+    expiresAt: z.ZodOptional<z.ZodString>;
+    /** Provider account identifier (e.g. GitHub username). */
+    accountId: z.ZodOptional<z.ZodString>;
+    /** Arbitrary provider-specific metadata. */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "oauth";
+    accessToken: string;
+    refreshToken?: string | undefined;
+    expiresAt?: string | undefined;
+    accountId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    type: "oauth";
+    accessToken: string;
+    refreshToken?: string | undefined;
+    expiresAt?: string | undefined;
+    accountId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+/** Custom/opaque credential — arbitrary key-value data. */
+export declare const CustomCredentialSchema: z.ZodObject<{
+    type: z.ZodLiteral<"custom">;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "custom";
+    data: Record<string, unknown>;
+}, {
+    type: "custom";
+    data: Record<string, unknown>;
+}>;
+/**
+ * Discriminated union of all credential types.
+ * - `api`    — simple API key
+ * - `oauth`  — OAuth 2.0 access/refresh tokens
+ * - `custom` — arbitrary opaque data
+ */
+export declare const CredentialSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"api">;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "api";
+    key: string;
+}, {
+    type: "api";
+    key: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    /** ISO-8601 datetime when the access token expires. */
+    expiresAt: z.ZodOptional<z.ZodString>;
+    /** Provider account identifier (e.g. GitHub username). */
+    accountId: z.ZodOptional<z.ZodString>;
+    /** Arbitrary provider-specific metadata. */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "oauth";
+    accessToken: string;
+    refreshToken?: string | undefined;
+    expiresAt?: string | undefined;
+    accountId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    type: "oauth";
+    accessToken: string;
+    refreshToken?: string | undefined;
+    expiresAt?: string | undefined;
+    accountId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"custom">;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "custom";
+    data: Record<string, unknown>;
+}, {
+    type: "custom";
+    data: Record<string, unknown>;
+}>]>;
+export type ApiCredential = z.infer<typeof ApiCredentialSchema>;
+export type OAuthCredential = z.infer<typeof OAuthCredentialSchema>;
+export type CustomCredential = z.infer<typeof CustomCredentialSchema>;
+export type Credential = z.infer<typeof CredentialSchema>;

package/dist/credentials/credentials.types.d.ts

@@ -0,0 +1,118 @@
+import type { Credential } from "./credentials.schema";
+export type { ApiCredential, Credential, CustomCredential, OAuthCredential, } from "./credentials.schema";
+/**
+ * Persisted credential data.
+ *
+ * Top-level keys are scopes:
+ * - `"$global"` — credentials available to all strategies.
+ * - Any other key — a strategy name for strategy-scoped overrides.
+ *
+ * Within each scope, keys are provider IDs → credential objects.
+ *
+ * @example
+ * ```json
+ * {
+ *   "$global": { "anthropic": { "type": "api", "key": "sk-..." } },
+ *   "my-strategy": { "openai": { "type": "api", "key": "sk-..." } }
+ * }
+ * ```
+ */
+export type CredentialStoreData = Readonly<Record<string, Record<string, Credential>>>;
+/**
+ * Low-level storage backend for credential data.
+ *
+ * Implementations handle serialization, file I/O, and encryption.
+ * The store itself handles scoping, resolution priority, and env vars.
+ */
+export interface CredentialBackend {
+    /** Read all credential data from storage. Returns empty object if none exists. */
+    readAll(): Promise<CredentialStoreData>;
+    /** Write the full credential data to storage (atomic replace). */
+    writeAll(data: CredentialStoreData): Promise<void>;
+}
+/**
+ * Credential store — resolves, gets, sets, and removes credentials.
+ *
+ * Resolution priority (most specific wins):
+ * 1. Strategy-scoped credential (if `scope` is provided and not `"$global"`)
+ * 2. Environment variable (using well-known or custom env var mapping)
+ * 3. Global-scoped credential (`"$global"`)
+ */
+export interface CredentialStore {
+    /**
+     * Resolve the best credential for a provider.
+     *
+     * Checks strategy scope → env vars → global scope, returning the
+     * first match found. Returns `undefined` if no credential is available.
+     *
+     * @param providerId - The provider to resolve credentials for.
+     * @param scope - Optional strategy name. If omitted, only env vars and global scope are checked.
+     */
+    resolve(providerId: string, scope?: string): Promise<Credential | undefined>;
+    /**
+     * Get a credential from a specific scope (no fallback/resolution chain).
+     */
+    get(providerId: string, scope: string): Promise<Credential | undefined>;
+    /**
+     * Set a credential in a specific scope.
+     */
+    set(providerId: string, scope: string, credential: Credential): Promise<void>;
+    /**
+     * Remove a credential from a specific scope.
+     * Returns `true` if the credential existed and was removed.
+     */
+    remove(providerId: string, scope: string): Promise<boolean>;
+    /**
+     * List all provider IDs that have credentials in a given scope.
+     */
+    list(scope: string): Promise<string[]>;
+    /**
+     * List all scopes that have at least one credential.
+     */
+    listScopes(): Promise<string[]>;
+    /**
+     * Check whether credentials exist for a provider, without performing
+     * any network validation.
+     *
+     * Returns `"configured"` if a credential is resolvable via any of:
+     * strategy scope → environment variable → global scope. Returns
+     * `"none"` if no credential is available.
+     *
+     * @param providerId - The provider to check.
+     * @param scope - Optional strategy name. If omitted, only env vars and global scope are checked.
+     */
+    getAuthStatus(providerId: string, scope?: string): Promise<AuthStatus>;
+}
+/**
+ * Configuration-level authentication status for a provider.
+ *
+ * - `"none"` — no credential found in any source.
+ * - `"configured"` — a credential was found (env var, strategy scope, or global scope).
+ *
+ * This is a configuration check only; it never performs a network call
+ * to validate the credential works.
+ */
+export type AuthStatus = "none" | "configured";
+/**
+ * Maps a provider ID to the environment variable name(s) that
+ * typically contain its API key.
+ *
+ * The first env var in the array is the "primary" — the one we check
+ * first and suggest to users. Additional entries are aliases.
+ */
+export type EnvVarMap = Readonly<Record<string, readonly string[]>>;
+/** Options for creating a credential store. */
+export interface CreateCredentialStoreOptions {
+    /** The storage backend to use. */
+    readonly backend: CredentialBackend;
+    /**
+     * Additional env var mappings to merge with WELL_KNOWN_ENV_VARS.
+     * Provider IDs here override well-known entries for the same key.
+     */
+    readonly envVarOverrides?: EnvVarMap;
+    /**
+     * Override `process.env` for testing.
+     * @internal
+     */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}

package/dist/credentials/credentials.utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve the platform-aware data directory for comma-agents.
+ *
+ * Respects platform conventions:
+ * - macOS:   ~/Library/Application Support/comma-agents/
+ * - Windows: %LOCALAPPDATA%/comma-agents/ (fallback ~/AppData/Local)
+ * - Linux:   $XDG_DATA_HOME/comma-agents/ (fallback ~/.local/share)
+ *
+ * @example
+ * ```ts
+ * const dataDir = resolveDataDir();
+ * // macOS:   "/Users/alice/Library/Application Support/comma-agents"
+ * // Linux:   "/home/alice/.local/share/comma-agents"
+ * // Windows: "C:\\Users\\alice\\AppData\\Local\\comma-agents"
+ * ```
+ */
+export declare function resolveDataDir(): string;
+/** Default name for the credentials JSON file. */
+export declare const CREDENTIALS_FILENAME = "credentials.json";
+/**
+ * Resolve the default path to the credentials JSON file.
+ *
+ * Convenience wrapper: `join(resolveDataDir(), "credentials.json")`.
+ *
+ * @example
+ * ```ts
+ * const backend = createJsonFileBackend({ filePath: resolveCredentialsPath() });
+ * ```
+ */
+export declare function resolveCredentialsPath(): string;

package/dist/credentials/index.d.ts

@@ -0,0 +1,6 @@
+export { createJsonFileBackend } from "./backends/json-file";
+export { createCredentialStore } from "./credentials";
+export type { ApiCredential, Credential, CustomCredential, OAuthCredential, } from "./credentials.schema";
+export { ApiCredentialSchema, CredentialSchema, CustomCredentialSchema, OAuthCredentialSchema, } from "./credentials.schema";
+export type { AuthStatus, CreateCredentialStoreOptions, CredentialBackend, CredentialStore, CredentialStoreData, EnvVarMap, } from "./credentials.types";
+export { resolveCredentialsPath, resolveDataDir } from "./credentials.utils";