@kodax-ai/kodax 0.7.67 → 0.7.69

package/dist/sdk-experimental-memory.d.ts

@@ -0,0 +1,618 @@
+import { k as KodaXMessage } from './types-chunks/types.d-TTvpAGWf.js';
+
+/**
+ * @kodax-ai/agent Types
+ *
+ * 通用 Agent 类型定义
+ */
+
+type KodaXJsonPrimitive = string | number | boolean | null;
+type KodaXJsonValue = KodaXJsonPrimitive | KodaXJsonValue[] | {
+    [key: string]: KodaXJsonValue;
+};
+interface KodaXSessionEntryBase {
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+    /**
+     * Stable logical identity for this transcript item. Cloned/forked entries get
+     * a fresh physical `id` but keep their source entry's `logicalId`, allowing
+     * SDK hosts to group or fold cloned history without comparing content.
+     */
+    logicalId?: string;
+    /** Root physical entry id this item was cloned from, when it is a clone. */
+    sourceEntryId?: string;
+}
+interface KodaXSessionMessageEntry extends KodaXSessionEntryBase {
+    type: 'message';
+    message: KodaXMessage;
+}
+interface KodaXSessionCompactionEntry extends KodaXSessionEntryBase {
+    type: 'compaction';
+    summary: string;
+    firstKeptEntryId?: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    artifactLedgerId?: string;
+    reason?: string;
+    details?: KodaXJsonValue;
+    memorySeed?: KodaXCompactMemorySeed;
+    /**
+     * FEATURE_072: post-compact ledger summary + file-content messages that
+     * are inlined after the compaction summary at slicer time
+     * (`getSessionMessagesFromLineage`). Stored here so they leave the active
+     * path automatically when a new compaction entry is appended.
+     *
+     * NOTE: attachments are emitted by the slicer, NOT by `getContextMessagesForEntry`
+     * — preserving the latter's 1-to-1 contract that `entryMatchesContextMessage`
+     * and FEATURE_073's future slicing both depend on.
+     */
+    postCompactAttachments?: readonly KodaXMessage[];
+}
+interface KodaXSessionBranchSummaryEntry extends KodaXSessionEntryBase {
+    type: 'branch_summary';
+    summary: string;
+    fromId?: string;
+    details?: KodaXJsonValue;
+}
+interface KodaXSessionLabelEntry extends KodaXSessionEntryBase {
+    type: 'label';
+    targetId: string;
+    label?: string;
+}
+interface KodaXSessionArchiveMarkerEntry extends KodaXSessionEntryBase {
+    type: 'archive_marker';
+    /** Links to the corresponding batch in the .archive.jsonl sidecar file */
+    archiveBatchId: string;
+    /** Number of entries that were archived in this batch */
+    archivedEntryCount: number;
+    /** Brief summary of the archived content */
+    summary: string;
+}
+interface KodaXSessionRewindMarkerEntry extends KodaXSessionEntryBase {
+    type: 'rewind_marker';
+    targetId: string;
+    fromId?: string;
+    truncatedCount: number;
+    summary: string;
+}
+interface KodaXSessionClientNoticeEntry extends KodaXSessionEntryBase {
+    type: 'client_notice';
+    source: string;
+    content: string;
+    turnId?: string;
+    payload?: KodaXJsonValue;
+}
+interface KodaXMemoryOutcomeDigest {
+    readonly id: string;
+    readonly reviewKey: string;
+    readonly sessionId: string;
+    readonly branchId: string;
+    readonly sequence: number;
+    readonly objective: string;
+    readonly actionSignature?: string;
+    readonly approach: string;
+    readonly outcome: 'succeeded' | 'failed';
+    readonly summary: string;
+    readonly preconditions?: string;
+    readonly lesson?: string;
+    readonly evidenceRefs: readonly string[];
+    readonly evidence?: readonly KodaXMemoryOutcomeEvidence[];
+    readonly memoryInfluence?: readonly KodaXMemoryInfluenceRef[];
+    readonly visibility: 'prompt_safe' | 'private' | 'sensitive';
+    readonly createdAt: string;
+}
+interface KodaXMemoryOutcomeEvidence {
+    readonly ref: string;
+    readonly grade: 'authoritative' | 'verified' | 'corroborated' | 'observed' | 'inferred';
+    readonly source: 'user' | 'host' | 'tool' | 'environment' | 'agent';
+    readonly observedAt: string;
+}
+interface KodaXMemoryInfluenceRef {
+    readonly decisionReceiptRef: string;
+    readonly grade: 'direct' | 'supporting' | 'exposed' | 'unknown';
+}
+interface KodaXSessionMemoryOutcomeDigestEntry extends KodaXSessionEntryBase {
+    readonly type: 'memory_outcome_digest';
+    readonly digest: KodaXMemoryOutcomeDigest;
+}
+interface KodaXSessionMemoryReviewReceiptEntry extends KodaXSessionEntryBase {
+    readonly type: 'memory_review_receipt';
+    readonly reviewKey: string;
+    readonly proposalIds: readonly string[];
+    readonly status: 'completed' | 'no_action';
+    readonly completedAt: string;
+}
+type KodaXGoalStatus = 'active' | 'paused' | 'budget_limited' | 'blocked' | 'complete';
+/**
+ * Persistent user-set goal state. v0.7.44 FEATURE_192 — backs the
+ * `/goal` slash command and the get_goal / create_goal / update_goal
+ * tools.
+ *
+ * Persistence model: each lifecycle event (create / update / pause /
+ * resume / clear / budget_limited / blocked / complete) appends a
+ * `KodaXSessionGoalEntry` carrying a frozen `KodaXGoalState` snapshot
+ * to the session lineage. `readLatestGoalFromBranch` walks the active
+ * branch's message-entry IDs and returns the latest goal entry whose
+ * parentId belongs to that branch — so forks and rewinds naturally
+ * drop goals attached to abandoned message paths.
+ */
+interface KodaXGoalState {
+    readonly version: 1;
+    /** `${createdAt}-${rand}` — stable across updates of the same goal. */
+    readonly id: string;
+    readonly objective: string;
+    readonly status: KodaXGoalStatus;
+    /** Optional explicit token budget; null when the user did not set one. */
+    readonly tokenBudget: number | null;
+    readonly tokensUsed: number;
+    readonly timeUsedSeconds: number;
+    /** Consecutive turns the model has reported the same blocker. */
+    readonly blockerTurnCount: number;
+    /** The blocker_kind string the model last reported, or null. */
+    readonly lastBlockerKind: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+type KodaXGoalEventType = 'created' | 'updated' | 'paused' | 'resumed' | 'cleared' | 'budget_limited' | 'blocked' | 'complete';
+interface KodaXSessionGoalEntry extends KodaXSessionEntryBase {
+    type: 'goal';
+    /** Snapshot at time of event; `null` only when `event === 'cleared'`. */
+    goal: KodaXGoalState | null;
+    event: KodaXGoalEventType;
+}
+type KodaXSessionEntry = KodaXSessionMessageEntry | KodaXSessionCompactionEntry | KodaXSessionBranchSummaryEntry | KodaXSessionLabelEntry | KodaXSessionArchiveMarkerEntry | KodaXSessionRewindMarkerEntry | KodaXSessionClientNoticeEntry | KodaXSessionMemoryOutcomeDigestEntry | KodaXSessionMemoryReviewReceiptEntry | KodaXSessionGoalEntry;
+interface KodaXSessionArtifactLedgerEntry {
+    id: string;
+    kind: 'file_read' | 'file_modified' | 'file_created' | 'file_deleted' | 'path_scope' | 'search_scope' | 'command_scope' | 'check_result' | 'decision' | 'image_input' | 'tombstone';
+    sourceTool?: string;
+    action?: string;
+    target: string;
+    displayTarget?: string;
+    summary?: string;
+    sessionEntryId?: string;
+    timestamp: string;
+    metadata?: Record<string, KodaXJsonValue>;
+}
+interface KodaXCompactMemoryProgress {
+    completed: string[];
+    inProgress: string[];
+    blockers: string[];
+}
+interface KodaXCompactMemorySeed {
+    objective?: string;
+    constraints: string[];
+    progress: KodaXCompactMemoryProgress;
+    keyDecisions: string[];
+    nextSteps: string[];
+    keyContext: string[];
+    importantTargets: string[];
+    tombstones: string[];
+}
+interface KodaXSessionLineage {
+    version: 2;
+    activeEntryId: string | null;
+    entries: KodaXSessionEntry[];
+}
+
+interface MemoryContextIdentity {
+    readonly tenantId: string;
+    readonly workspaceId?: string;
+    readonly userId?: string;
+    readonly agentId: string;
+    readonly projectId?: string;
+    readonly sessionId: string;
+}
+interface MemoryApplicability {
+    readonly tenantId: string;
+    readonly workspaceId?: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+    readonly projectId?: string;
+    readonly sessionId?: string;
+}
+
+type MemoryRefKind = 'working_context' | 'session_trace' | 'artifact_ledger' | 'learning_proposal' | 'memdir' | 'skill' | 'workflow_run' | 'reasoning_report' | 'self_manual' | 'project_doc';
+
+type MemoryScope = 'turn' | 'session' | 'project' | 'workspace' | 'agent' | 'user' | 'builtin';
+type MemoryClaimKind = 'fact' | 'policy' | 'preference' | 'procedure' | 'episode';
+type MemoryLifecycle = 'pending' | 'active' | 'provisional' | 'trusted' | 'stale' | 'quarantined' | 'archived' | 'readonly';
+type MemoryAuthority = 'read_only' | 'proposal_only' | 'approved_write';
+type MemoryVisibility = 'prompt_safe' | 'private' | 'sensitive';
+interface MemoryItemRef {
+    readonly kind: MemoryRefKind;
+    readonly id: string;
+    readonly scope: MemoryScope;
+    readonly scopeId?: string;
+    readonly applicability?: MemoryApplicability;
+    readonly claimKind?: MemoryClaimKind;
+    readonly claimKey?: string;
+    readonly actionSignature?: string;
+    readonly title?: string;
+    readonly owner: 'user' | 'project' | 'kodax' | 'external';
+    readonly lifecycle: MemoryLifecycle;
+    readonly authority: MemoryAuthority;
+    readonly visibility: MemoryVisibility;
+    readonly sourceRefs: readonly string[];
+    readonly relatedRefs: readonly string[];
+    readonly version?: string;
+    readonly bodyFingerprint?: string;
+    readonly storageUri?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly lastUsedAt?: string;
+    readonly pinned?: boolean;
+    readonly applyReceiptRef?: string;
+    readonly expectedFingerprint?: string;
+    readonly resultingFingerprint?: string;
+}
+interface MemoryRefFilter {
+    readonly kinds?: readonly MemoryRefKind[];
+    readonly scopes?: readonly MemoryScope[];
+    readonly lifecycles?: readonly MemoryLifecycle[];
+    readonly includePrivate?: boolean;
+    readonly includeSensitive?: boolean;
+    readonly query?: string;
+}
+interface MemoryBodySnapshot {
+    readonly ref: MemoryItemRef;
+    readonly body: string;
+    readonly bodyFingerprint: string;
+    readonly frontmatter?: Readonly<Record<string, string>>;
+    readonly readAt: string;
+    readonly warnings: readonly string[];
+}
+type MemoryProposalAction = 'no_op' | 'link_refs' | 'write_memdir' | 'patch_memdir' | 'handoff_to_skill_loop' | 'quarantine' | 'archive' | 'conflict_report';
+interface MemoryApplyPreview {
+    readonly summary: string;
+    readonly changedRefs: readonly MemoryItemRef[];
+    readonly changedPaths: readonly string[];
+    readonly beforeFingerprints: Readonly<Record<string, string>>;
+    readonly afterFingerprints?: Readonly<Record<string, string>>;
+    readonly diff?: string;
+    readonly warnings: readonly string[];
+}
+interface MemoryActionProposal {
+    readonly id: string;
+    readonly action: MemoryProposalAction;
+    readonly targetRefs: readonly MemoryItemRef[];
+    readonly sourceRefs: readonly MemoryItemRef[];
+    readonly expectedFingerprints: Readonly<Record<string, string>>;
+    readonly rationale: string;
+    readonly risk: 'low' | 'medium' | 'high';
+    readonly preview: MemoryApplyPreview;
+    readonly requiresApproval: true;
+    readonly createdAt: string;
+}
+interface MemoryApplyResult {
+    readonly proposalId: string;
+    readonly applied: boolean;
+    readonly changedRefs: readonly MemoryItemRef[];
+    readonly changedPaths: readonly string[];
+    readonly skippedReason?: string;
+    readonly warnings: readonly string[];
+}
+interface MemoryRejectResult {
+    readonly proposalId: string;
+    readonly rejected: boolean;
+    readonly skippedReason?: string;
+    readonly review?: MemoryReviewPlan;
+    readonly warnings: readonly string[];
+}
+interface MemoryLifecycleOperationResult {
+    readonly refId: string;
+    readonly operation: 'archive' | 'forget' | 'purge';
+    readonly acknowledged: boolean;
+    readonly residualSourceRefs: readonly string[];
+    readonly warnings: readonly string[];
+}
+interface MemoryCuratorInput {
+    readonly includePrivate?: boolean;
+    readonly includeSensitive?: boolean;
+}
+interface MemoryAutoCuratorInput extends MemoryCuratorInput {
+    readonly enabled?: boolean;
+    readonly intervalMs?: number;
+    readonly minRefs?: number;
+}
+type MemoryAutoCuratorSkipReason = 'disabled' | 'not_due' | 'insufficient_refs';
+interface MemoryAutoCuratorResult {
+    readonly ran: boolean;
+    readonly skippedReason?: MemoryAutoCuratorSkipReason;
+    readonly report?: MemoryGovernanceReport;
+    readonly reportPath?: string;
+    readonly nextEligibleAt?: string;
+}
+type MemoryGovernanceFindingKind = 'duplicate' | 'conflict' | 'stale' | 'quarantined' | 'orphaned' | 'no_op';
+interface MemoryGovernanceFinding {
+    readonly kind: MemoryGovernanceFindingKind;
+    readonly severity: 'info' | 'warning' | 'error';
+    readonly refIds: readonly string[];
+    readonly summary: string;
+    readonly suggestedAction: MemoryProposalAction;
+}
+interface MemoryGovernanceReport {
+    readonly reportId: string;
+    readonly generatedAt: string;
+    readonly findings: readonly MemoryGovernanceFinding[];
+    readonly warnings: readonly string[];
+}
+interface MemoryPackInput {
+    readonly task: string;
+    readonly identity?: MemoryContextIdentity;
+    readonly decisionIntent?: string;
+    readonly actionSignature?: string;
+    readonly maxCandidates?: number;
+    readonly maxHints?: number;
+    readonly includePrivate?: boolean;
+    readonly includeSensitive?: boolean;
+    readonly includeSnippets?: boolean;
+    readonly ignoreMemory?: boolean;
+    readonly purpose?: 'automatic' | 'deliberate_query';
+}
+interface MemoryPackHint {
+    readonly ref: MemoryItemRef;
+    readonly hook: string;
+    readonly reason: string;
+    readonly bodySnippet?: string;
+    readonly bodyFingerprint?: string;
+}
+interface MemoryPack {
+    readonly generatedAt: string;
+    readonly taskFingerprint: string;
+    readonly memoryRevision: string;
+    readonly candidates: readonly MemoryPackHint[];
+    readonly promptHints: readonly MemoryPackHint[];
+    /** @deprecated Use promptHints. Retained for F228 source compatibility. */
+    readonly hints: readonly MemoryPackHint[];
+    readonly omitted: readonly string[];
+    readonly traceMetadata: MemoryPackTraceMetadata;
+}
+interface MemoryPackTraceMetadata {
+    readonly selectedRefIds: readonly string[];
+    readonly omittedRefIds: readonly string[];
+    readonly taskFingerprint: string;
+    readonly suppressed: boolean;
+}
+type MemoryReviewTrigger = 'user_correction' | 'explicit_remember' | 'explicit_forget' | 'proposal_rejected' | 'conflict_detected' | 'episode_completed';
+interface MemoryReviewCandidateRef {
+    readonly ref: MemoryItemRef;
+    readonly bodySnippet?: string;
+    readonly bodyFingerprint?: string;
+    readonly warnings: readonly string[];
+}
+interface MemoryReviewInput {
+    readonly trigger: MemoryReviewTrigger;
+    readonly userFeedback?: string;
+    readonly episodeDigest?: KodaXMemoryOutcomeDigest;
+    readonly task?: string;
+    readonly sourceRefs?: readonly string[];
+    readonly candidateRefIds?: readonly string[];
+    readonly includePrivate?: boolean;
+    readonly includeSensitive?: boolean;
+    readonly maxRefs?: number;
+}
+interface MemoryReviewModelInput {
+    readonly trigger: MemoryReviewTrigger;
+    readonly userFeedback: string;
+    readonly task?: string;
+    readonly sourceRefs: readonly string[];
+    readonly candidateRefs: readonly MemoryReviewCandidateRef[];
+    readonly warnings: readonly string[];
+}
+interface MemoryReviewDraftAction {
+    readonly action: MemoryProposalAction;
+    readonly targetRefIds: readonly string[];
+    readonly summary: string;
+    readonly rationale: string;
+    readonly confidence: 'low' | 'medium' | 'high';
+    readonly risk: 'low' | 'medium' | 'high';
+    readonly requiresApproval: true;
+    readonly proposedBody?: string;
+    readonly claimKind?: MemoryClaimKind;
+    readonly claimKey?: string;
+    readonly actionSignature?: string;
+    readonly preconditions?: string;
+    readonly counterexamples?: readonly string[];
+    readonly relationship?: 'same_claim' | 'condition_refinement' | 'conflict';
+}
+interface MemoryReviewPlan {
+    readonly trigger: MemoryReviewTrigger;
+    readonly createdAt: string;
+    readonly sourceRefs: readonly string[];
+    readonly candidateRefs: readonly MemoryReviewCandidateRef[];
+    readonly actions: readonly MemoryReviewDraftAction[];
+    readonly warnings: readonly string[];
+    readonly episodeDigest?: KodaXMemoryOutcomeDigest;
+}
+interface MemoryEpisodeReviewResult {
+    readonly plan: MemoryReviewPlan;
+    readonly proposalIds: readonly string[];
+    readonly appliedProposalIds: readonly string[];
+    readonly decisions: readonly MemoryReviewPersistenceDecision[];
+    readonly warnings: readonly string[];
+}
+type MemoryReviewPersistenceKind = 'create' | 'evidence_update' | 'condition_refinement' | 'conflict' | 'no_action' | 'reject' | 'quarantine';
+interface MemoryReviewPersistenceDecision {
+    readonly actionIndex: number;
+    readonly kind: MemoryReviewPersistenceKind;
+    readonly reason: string;
+    readonly existingRefId?: string;
+    readonly proposalId?: string;
+}
+type MemoryReviewRunner = (input: MemoryReviewModelInput) => Promise<MemoryReviewPlan>;
+interface MemoryController {
+    listInbox(): Promise<readonly MemoryActionProposal[]>;
+    showProposal(id: string): Promise<MemoryActionProposal | undefined>;
+    approveProposal(id: string, expectedFingerprints: Readonly<Record<string, string>>): Promise<MemoryApplyResult>;
+    rejectProposal(id: string, reason?: string): Promise<MemoryRejectResult>;
+    listRefs(filter?: MemoryRefFilter): Promise<readonly MemoryItemRef[]>;
+    readRef(ref: MemoryItemRef): Promise<MemoryBodySnapshot>;
+    runCurator(input?: MemoryCuratorInput): Promise<MemoryGovernanceReport>;
+    maybeRunAutoCurator(input?: MemoryAutoCuratorInput): Promise<MemoryAutoCuratorResult>;
+    buildMemoryPack(input: MemoryPackInput): Promise<MemoryPack>;
+    reviewMemoryFeedback(input: MemoryReviewInput): Promise<MemoryReviewPlan>;
+    persistReviewPlan(plan: MemoryReviewPlan): Promise<readonly string[]>;
+    reviewEpisode(digest: KodaXMemoryOutcomeDigest, signal?: AbortSignal): Promise<MemoryEpisodeReviewResult>;
+    archiveRef(id: string): Promise<MemoryLifecycleOperationResult>;
+    forgetRef(id: string): Promise<MemoryLifecycleOperationResult>;
+    purgeRef(id: string): Promise<MemoryLifecycleOperationResult>;
+}
+type MemoryEvent = {
+    readonly type: 'proposal.created';
+    readonly proposalId: string;
+} | {
+    readonly type: 'proposal.approved';
+    readonly proposalId: string;
+} | {
+    readonly type: 'proposal.rejected';
+    readonly proposalId: string;
+} | {
+    readonly type: 'curator.completed';
+    readonly reportId: string;
+} | {
+    readonly type: 'pack.selected';
+    readonly refIds: readonly string[];
+} | {
+    readonly type: 'review.completed';
+    readonly trigger: MemoryReviewTrigger;
+    readonly actionCount: number;
+};
+
+/** Source-controlled F260 policy identity. Not a runtime configuration knob. */
+declare const MEMORY_POLICY_VERSION = "f260-v0.7.68.2";
+
+interface CreateMemoryControlPlaneOptions {
+    readonly cwd: string;
+    readonly identity?: MemoryContextIdentity;
+    readonly learningStorePath?: string;
+    readonly memoryRoot?: string;
+    readonly projectDocs?: readonly string[];
+    readonly extraRefs?: readonly MemoryItemRef[];
+    readonly sessionId?: string;
+    readonly sessionLineage?: KodaXSessionLineage;
+    readonly artifactLedger?: readonly KodaXSessionArtifactLedgerEntry[];
+    readonly now?: () => string;
+    readonly onEvent?: (event: MemoryEvent) => void;
+    readonly discoverSkills?: boolean;
+    readonly memoryReviewer?: MemoryReviewRunner;
+}
+declare function createMemoryControlPlane(options: CreateMemoryControlPlaneOptions): MemoryController;
+
+type MemoryEvidenceGrade = 'authoritative' | 'verified' | 'corroborated' | 'observed' | 'inferred';
+interface MemoryEvidenceRef {
+    readonly ref: string;
+    readonly requestedGrade: MemoryEvidenceGrade;
+    readonly source: 'user' | 'host' | 'tool' | 'environment' | 'agent';
+    readonly observedAt: string;
+}
+type MemorySourcePolicy = (evidence: MemoryEvidenceRef) => MemoryEvidenceGrade;
+type MemoryObservationKind = 'constraint' | 'fact' | 'outcome' | 'correction';
+interface MemoryObservation {
+    readonly id: string;
+    readonly sequence: number;
+    readonly kind: MemoryObservationKind;
+    readonly summary: string;
+    readonly evidence: readonly MemoryEvidenceRef[];
+    readonly visibility: MemoryVisibility;
+    readonly claimKey?: string;
+    readonly actionSignature?: string;
+    readonly occurredAt: string;
+    readonly metadata?: Readonly<Record<string, string | number | boolean>>;
+}
+interface MemoryRecallInput {
+    readonly decisionRevision: string;
+    readonly objective: string;
+    readonly decisionContext: string;
+    readonly decisionIntent: string;
+    readonly actionSignature?: string;
+    readonly throughSequence: number;
+}
+interface MemoryQueryInput {
+    readonly decisionRevision: string;
+    readonly need: string;
+    readonly actionSignature?: string;
+    readonly throughSequence: number;
+}
+interface MemoryReminder {
+    readonly content: string;
+    readonly evidenceRefs: readonly string[];
+}
+interface MemoryRecallCandidate {
+    readonly refId: string;
+    readonly claim: string;
+    readonly claimKind?: string;
+}
+interface MemoryRecallRunnerInput {
+    readonly objective: string;
+    readonly decisionContext: string;
+    readonly decisionIntent: string;
+    readonly candidates: readonly MemoryRecallCandidate[];
+    readonly signal: AbortSignal;
+}
+type MemoryRecallRunner = (input: MemoryRecallRunnerInput) => Promise<{
+    readonly selectedRefIds: readonly string[];
+}>;
+type MemorySelectionMode = 'task_hint' | 'exact' | 'semantic_prefetch' | 'deliberate_query';
+interface MemoryDecisionReceipt {
+    readonly id: string;
+    readonly decisionEpoch: string;
+    readonly decisionRevision: string;
+    readonly policyVersion: string;
+    readonly candidateSetFingerprint: string;
+    readonly candidateRefs: readonly string[];
+    readonly selectedRefs: readonly string[];
+    readonly injectedRefs: readonly string[];
+    readonly selectionModes: readonly MemorySelectionMode[];
+    readonly actionSignature?: string;
+    readonly throughSequence: number;
+}
+type MemoryAgentTraceEvent = {
+    readonly type: 'recall.prefetch.completed' | 'recall.prefetch.failed' | 'recall.prefetch.discarded' | 'query.failed' | 'review.timed_out';
+    readonly key: string;
+    readonly detail?: string;
+} | {
+    readonly type: 'memory.decision';
+    readonly receipt: MemoryDecisionReceipt;
+};
+interface MemorySessionInput {
+    readonly identity: MemoryContextIdentity;
+    readonly objective: string;
+}
+interface MemoryEpisodeOutcome {
+    readonly status: 'succeeded' | 'failed' | 'cancelled';
+    readonly summary: string;
+    readonly evidence: readonly MemoryEvidenceRef[];
+}
+type PersistedOutcomeDigest = KodaXMemoryOutcomeDigest;
+interface MemorySession {
+    observe(observation: MemoryObservation): void;
+    recall(input: MemoryRecallInput): MemoryReminder | undefined;
+    query(input: MemoryQueryInput): Promise<MemoryReminder | undefined>;
+    rewind(input: {
+        readonly throughSequence: number;
+    }): void;
+    complete(outcome: MemoryEpisodeOutcome): Promise<void>;
+    close(options?: {
+        readonly drain?: boolean;
+    }): Promise<void>;
+}
+interface MemoryAgent {
+    startSession(input: MemorySessionInput): Promise<MemorySession>;
+}
+interface CreateMemoryAgentOptions {
+    readonly controlPlane: MemoryController;
+    readonly initialMemoryPack?: MemoryPack;
+    readonly now?: () => string;
+    readonly persistOutcomeDigest?: (digest: PersistedOutcomeDigest) => Promise<void>;
+    readonly reviewEpisode?: (digest: PersistedOutcomeDigest, signal: AbortSignal) => Promise<void>;
+    readonly reviewTimeoutMs?: number;
+    readonly recallRunner?: MemoryRecallRunner;
+    readonly onTrace?: (event: MemoryAgentTraceEvent) => void;
+    readonly sourcePolicy?: MemorySourcePolicy;
+}
+
+declare function createMemoryAgent(options: CreateMemoryAgentOptions): MemoryAgent;
+
+export { MEMORY_POLICY_VERSION, createMemoryAgent, createMemoryControlPlane };
+export type { CreateMemoryAgentOptions, MemoryAgent, MemoryAgentTraceEvent, MemoryApplicability, MemoryContextIdentity, MemoryController, MemoryDecisionReceipt, MemoryEpisodeOutcome, MemoryEvidenceGrade, MemoryEvidenceRef, MemoryObservation, MemoryObservationKind, MemoryPack, MemoryQueryInput, MemoryRecallCandidate, MemoryRecallInput, MemoryRecallRunner, MemoryRecallRunnerInput, MemoryReminder, MemorySelectionMode, MemorySession, MemorySessionInput, MemorySourcePolicy, PersistedOutcomeDigest };

package/dist/sdk-experimental-memory.js

@@ -0,0 +1,2 @@
+// @kodax-ai/kodax — bundled distribution. See docs/ADR.md ADR-022 + ADR-024.
+import{a as r}from"./chunks/chunk-I4TPQEJN.js";import{ea as o,k as e}from"./chunks/chunk-AWMTNUDS.js";import"./chunks/chunk-NGHQIGVW.js";import"./chunks/chunk-ONUPGMER.js";export{e as MEMORY_POLICY_VERSION,r as createMemoryAgent,o as createMemoryControlPlane};

package/dist/sdk-llm.d.ts

@@ -1,15 +1,22 @@
-import { o as KodaXProviderCapabilityProfile, a7 as KodaXVerifyStrategy, a6 as KodaXVerifyCredentialResult, j as KodaXMessage, G as KodaXReasoningRequest, $ as KodaXTokenUsage, c as KodaXContentBlock, a as KodaXCacheBoundary } from './types-chunks/types.d-Bp4Lm1jv.js';
-export { K as KodaXAssuranceIntent, b as KodaXChildFanoutClass, d as KodaXCustomProviderConfig, e as KodaXExecutionMode, f as KodaXExecutionPattern, g as KodaXHarnessProfile, h as KodaXImageBlock, i as KodaXListModelsResult, k as KodaXModelDescriptor, l as KodaXMutationSurface, m as KodaXNormalizedReasoningRequest, n as KodaXProtocolFamily, p as KodaXProviderConfig, q as KodaXProviderContextFidelity, r as KodaXProviderConversationSemantics, s as KodaXProviderEvidenceSupport, t as KodaXProviderLongRunningSupport, u as KodaXProviderMcpSupport, v as KodaXProviderMultimodalSupport, w as KodaXProviderSessionSupport, x as KodaXProviderStreamOptions, y as KodaXProviderToolCallingFidelity, z as KodaXProviderTransport, A as KodaXReasoningCapability, B as KodaXReasoningEffortPreset, C as KodaXReasoningEffortRequest, D as KodaXReasoningEffortWireStrategy, E as KodaXReasoningMode, F as KodaXReasoningProfile, H as KodaXRedactedThinkingBlock, I as KodaXReviewScale, J as KodaXRiskLevel, L as KodaXStableEffortIntent, M as KodaXStreamResult, N as KodaXTaskActionability, O as KodaXTaskBudgetOverrides, P as KodaXTaskComplexity, Q as KodaXTaskFamily, R as KodaXTaskResultMetadata, S as KodaXTaskResultSource, T as KodaXTaskRoutingDecision, U as KodaXTaskType, V as KodaXTaskWorkIntent, W as KodaXTextBlock, X as KodaXThinkingBlock, Y as KodaXThinkingBudgetMap, Z as KodaXThinkingDepth, _ as KodaXThinkingWireStrategy, a0 as KodaXToolDefinition, a1 as KodaXToolResultBlock, a2 as KodaXToolResultContentItem, a3 as KodaXToolResultImageItem, a4 as KodaXToolResultTextItem, a5 as KodaXToolUseBlock, a8 as KodaXWireReasoningEffort } from './types-chunks/types.d-Bp4Lm1jv.js';
-export { K as KODAX_DEFAULT_PROVIDER, a as KODAX_DEFAULT_THINKING_BUDGETS, b as KODAX_PROVIDERS, c as KODAX_PROVIDER_SNAPSHOTS, d as KODAX_REASONING_MODE_SEQUENCE, e as KODAX_REASONING_SAFETY_RESERVE, f as KODAX_STABLE_EFFORT_INTENTS, g as KodaXAnthropicCompatProvider, h as KodaXError, i as KodaXModelCapabilities, j as KodaXNetworkError, k as KodaXOpenAICompatProvider, l as KodaXProviderError, m as KodaXRateLimitError, n as KodaXToolCallIdError, P as ProviderName, R as ResolveWireEffortInput, o as ResolvedWireEffort, p as clampThinkingBudget, q as clearRuntimeModelProviders, r as createCustomProvider, s as effortToLegacyReasoningMode, t as getAvailableProviderNames, u as getCustomModelCapabilities, v as getCustomProvider, w as getCustomProviderList, x as getCustomProviderModelDescriptors, y as getCustomProviderModels, z as getCustomProviderNames, A as getDefaultThinkingDepthForMode, B as getModelCapabilities, C as getProvider, D as getProviderConfiguredCapabilityProfile, E as getProviderConfiguredReasoningCapability, F as getProviderList, G as getProviderModel, H as getProviderModelDescriptors, I as getProviderModels, J as getReasoningCapability, L as getRuntimeModelProvider, M as getRuntimeModelProviderNames, N as isCustomProviderName, O as isKnownProvider, Q as isProviderConfigured, S as isProviderName, T as isReasoningEnabled, U as isRuntimeModelProviderName, V as listAllModelCapabilities, W as listBuiltinModelCapabilities, X as listCustomProviderModelCapabilities, Y as listProviderModels, Z as mapDepthToOpenAIReasoningEffort, _ as mapLegacyReasoningModeToEffortIntent, $ as normalizeReasoningEffortValue, a0 as normalizeReasoningRequest, a1 as parseReasoningEffortEnv, a2 as registerCustomProviders, a3 as registerModelProvider, a4 as resolveModelCapabilities, a5 as resolveProvider, a6 as resolveProviderModelDescriptors, a7 as resolveReasoningEffort, a8 as resolveReasoningEffortForModelSwitch, a9 as resolveThinkingBudget, aa as resolveWireEffort, ab as validateCustomProviderConfig, ac as verifyProviderCredential } from './types-chunks/resolver.d-CGkfRULj.js';
-import { a as CostTracker } from './types-chunks/cost-tracker.d-CBLk1fiD.js';
-export { C as CostRate, D as DEFAULT_COST_RATES, K as KodaXLlmTimeoutConfig, b as KodaXResolvedLlmTimeoutConfig, P as ProviderCostSummary, R as RetryRecord, S as SessionCostSummary, T as TokenUsageRecord, c as calculateCost, d as createCostTracker, f as formatCost, e as formatCostReport, g as getCostRate, h as getSummary, p as parseTimeoutSecEnvMs, r as recordRetry, i as recordUsage, j as resolveLlmTimeoutConfig, t as timeoutSecToMs } from './types-chunks/cost-tracker.d-CBLk1fiD.js';
-export { C as CapabilityCache, a as CapabilityCacheEntry, b as CapabilityCacheSource, c as addRejectedEffort, d as capabilityCacheKey, g as getRejectedEfforts, n as narrowReasoningProfile, r as removeCacheEntry, s as sanitizeCapabilityCache } from './types-chunks/capability-learning.d-BQB0M70w.js';
-import { K as KodaXBaseProvider } from './types-chunks/base.d-DalIRhbb.js';
-export { a as KodaXOnRetryAfterCallback, b as KodaXRetryAfterEvent, P as ParseRetryAfterOptions, R as RetryAfterResult, c as RetryAfterSource, e as extractHeadersFromError, p as parseRetryAfter } from './types-chunks/base.d-DalIRhbb.js';
+import { p as KodaXProviderCapabilityProfile, a8 as KodaXVerifyStrategy, a7 as KodaXVerifyCredentialResult, k as KodaXMessage, H as KodaXReasoningRequest, a0 as KodaXTokenUsage, c as KodaXContentBlock, a as KodaXCacheBoundary } from './types-chunks/types.d-TTvpAGWf.js';
+export { K as KodaXAssuranceIntent, b as KodaXChildFanoutClass, d as KodaXCustomProviderConfig, e as KodaXEphemeralSuffix, f as KodaXExecutionMode, g as KodaXExecutionPattern, h as KodaXHarnessProfile, i as KodaXImageBlock, j as KodaXListModelsResult, l as KodaXModelDescriptor, m as KodaXMutationSurface, n as KodaXNormalizedReasoningRequest, o as KodaXProtocolFamily, q as KodaXProviderConfig, r as KodaXProviderContextFidelity, s as KodaXProviderConversationSemantics, t as KodaXProviderEvidenceSupport, u as KodaXProviderLongRunningSupport, v as KodaXProviderMcpSupport, w as KodaXProviderMultimodalSupport, x as KodaXProviderSessionSupport, y as KodaXProviderStreamOptions, z as KodaXProviderToolCallingFidelity, A as KodaXProviderTransport, B as KodaXReasoningCapability, C as KodaXReasoningEffortPreset, D as KodaXReasoningEffortRequest, E as KodaXReasoningEffortWireStrategy, F as KodaXReasoningMode, G as KodaXReasoningProfile, I as KodaXRedactedThinkingBlock, J as KodaXReviewScale, L as KodaXRiskLevel, M as KodaXStableEffortIntent, N as KodaXStreamResult, O as KodaXTaskActionability, P as KodaXTaskBudgetOverrides, Q as KodaXTaskComplexity, R as KodaXTaskFamily, S as KodaXTaskResultMetadata, T as KodaXTaskResultSource, U as KodaXTaskRoutingDecision, V as KodaXTaskType, W as KodaXTaskWorkIntent, X as KodaXTextBlock, Y as KodaXThinkingBlock, Z as KodaXThinkingBudgetMap, _ as KodaXThinkingDepth, $ as KodaXThinkingWireStrategy, a1 as KodaXToolDefinition, a2 as KodaXToolResultBlock, a3 as KodaXToolResultContentItem, a4 as KodaXToolResultImageItem, a5 as KodaXToolResultTextItem, a6 as KodaXToolUseBlock, a9 as KodaXWireReasoningEffort } from './types-chunks/types.d-TTvpAGWf.js';
+export { K as KODAX_DEFAULT_PROVIDER, a as KODAX_DEFAULT_THINKING_BUDGETS, b as KODAX_PROVIDERS, c as KODAX_PROVIDER_SNAPSHOTS, d as KODAX_REASONING_MODE_SEQUENCE, e as KODAX_REASONING_SAFETY_RESERVE, f as KODAX_STABLE_EFFORT_INTENTS, g as KodaXAnthropicCompatProvider, h as KodaXError, i as KodaXModelCapabilities, j as KodaXNetworkError, k as KodaXOpenAICompatProvider, l as KodaXProviderError, m as KodaXRateLimitError, n as KodaXToolCallIdError, P as ProviderName, R as ResolveWireEffortInput, o as ResolvedWireEffort, p as clampThinkingBudget, q as clearRuntimeModelProviders, r as createCustomProvider, s as effortToLegacyReasoningMode, t as getAvailableProviderNames, u as getCustomModelCapabilities, v as getCustomProvider, w as getCustomProviderList, x as getCustomProviderModelDescriptors, y as getCustomProviderModels, z as getCustomProviderNames, A as getDefaultThinkingDepthForMode, B as getModelCapabilities, C as getProvider, D as getProviderConfiguredCapabilityProfile, E as getProviderConfiguredReasoningCapability, F as getProviderList, G as getProviderModel, H as getProviderModelDescriptors, I as getProviderModels, J as getReasoningCapability, L as getRuntimeModelProvider, M as getRuntimeModelProviderNames, N as isCustomProviderName, O as isKnownProvider, Q as isProviderConfigured, S as isProviderName, T as isReasoningEnabled, U as isRuntimeModelProviderName, V as listAllModelCapabilities, W as listBuiltinModelCapabilities, X as listCustomProviderModelCapabilities, Y as listProviderModels, Z as mapDepthToOpenAIReasoningEffort, _ as mapLegacyReasoningModeToEffortIntent, $ as normalizeReasoningEffortValue, a0 as normalizeReasoningRequest, a1 as parseReasoningEffortEnv, a2 as registerCustomProviders, a3 as registerModelProvider, a4 as resolveModelCapabilities, a5 as resolveProvider, a6 as resolveProviderModelDescriptors, a7 as resolveReasoningEffort, a8 as resolveReasoningEffortForModelSwitch, a9 as resolveThinkingBudget, aa as resolveWireEffort, ab as validateCustomProviderConfig, ac as verifyProviderCredential } from './types-chunks/resolver.d-CIVoGc97.js';
+import { a as CostTracker } from './types-chunks/cost-tracker.d-BeaenODW.js';
+export { C as CostRate, D as DEFAULT_COST_RATES, K as KodaXLlmTimeoutConfig, b as KodaXResolvedLlmTimeoutConfig, P as ProviderCostSummary, R as RetryRecord, S as SessionCostSummary, T as TokenUsageRecord, c as calculateCost, d as createCostTracker, f as formatCost, e as formatCostReport, g as getCostRate, h as getSummary, p as parseTimeoutSecEnvMs, r as recordRetry, i as recordUsage, j as resolveLlmTimeoutConfig, t as timeoutSecToMs } from './types-chunks/cost-tracker.d-BeaenODW.js';
+export { C as CapabilityCache, a as CapabilityCacheEntry, b as CapabilityCacheSource, c as addRejectedEffort, d as capabilityCacheKey, g as getRejectedEfforts, n as narrowReasoningProfile, r as removeCacheEntry, s as sanitizeCapabilityCache } from './types-chunks/capability-learning.d-WtsyRv3O.js';
+import { K as KodaXBaseProvider } from './types-chunks/base.d-CYjtB68X.js';
+export { a as KodaXOnRetryAfterCallback, b as KodaXRetryAfterEvent, P as ParseRetryAfterOptions, R as RetryAfterResult, c as RetryAfterSource, e as extractHeadersFromError, p as parseRetryAfter } from './types-chunks/base.d-CYjtB68X.js';
 export { C as CapabilityKind, a as CapabilityProvider, b as CapabilityResult } from './types-chunks/capability.d-3C62G8Eq.js';
 import '@anthropic-ai/sdk';
 import 'openai';
 
+/** Run a provider operation with an in-memory, run-scoped credential override. */
+declare function runWithProviderCredential<T>(provider: string, credential: string, operation: () => T): T;
+/** Internal provider lookup. The credential is never copied to config or diagnostics. */
+declare function getScopedProviderCredential(provider: string): string | undefined;
+/** Remove the active run credential from DTOs before diagnostics or persistence. */
+declare function redactScopedProviderCredential<T>(value: T): T;
+
 /**
  * KodaX AI Constants
  *
@@ -316,5 +323,5 @@ declare function stripCacheBoundaries<T extends {
     type: string;
 }>(blocks: readonly (T | KodaXCacheBoundary)[]): T[];
 
-export { CostTracker, KODAX_API_MIN_INTERVAL, KODAX_CAPPED_MAX_OUTPUT_TOKENS, KODAX_ESCALATED_MAX_OUTPUT_TOKENS, KODAX_MAX_TOKENS, KodaXBaseProvider, KodaXCacheBoundary, KodaXContentBlock, KodaXMessage, KodaXProviderCapabilityProfile, KodaXReasoningRequest, KodaXTokenUsage, KodaXVerifyCredentialResult, KodaXVerifyStrategy, WORKFLOW_MAX_CONCURRENCY_ABSOLUTE, WORKFLOW_MAX_CONCURRENCY_DEFAULT, classifyStopReason, classifyVerifyError, getCodexCliDefaultModel, getCodexCliKnownModels, getGeminiCliDefaultModel, getGeminiCliKnownModels, getRunScopedConfig, insertCacheBoundary, isCacheBoundary, isCleanStop, lowerCacheBoundaries, normalizeCapabilityProfile, parseToolInputWithSalvage, resolveWorkflowMaxConcurrency, runVerifyCredential, runWithScopedConfig, sideQuery, stripCacheBoundaries };
+export { CostTracker, KODAX_API_MIN_INTERVAL, KODAX_CAPPED_MAX_OUTPUT_TOKENS, KODAX_ESCALATED_MAX_OUTPUT_TOKENS, KODAX_MAX_TOKENS, KodaXBaseProvider, KodaXCacheBoundary, KodaXContentBlock, KodaXMessage, KodaXProviderCapabilityProfile, KodaXReasoningRequest, KodaXTokenUsage, KodaXVerifyCredentialResult, KodaXVerifyStrategy, WORKFLOW_MAX_CONCURRENCY_ABSOLUTE, WORKFLOW_MAX_CONCURRENCY_DEFAULT, classifyStopReason, classifyVerifyError, getCodexCliDefaultModel, getCodexCliKnownModels, getGeminiCliDefaultModel, getGeminiCliKnownModels, getRunScopedConfig, getScopedProviderCredential, insertCacheBoundary, isCacheBoundary, isCleanStop, lowerCacheBoundaries, normalizeCapabilityProfile, parseToolInputWithSalvage, redactScopedProviderCredential, resolveWorkflowMaxConcurrency, runVerifyCredential, runWithProviderCredential, runWithScopedConfig, sideQuery, stripCacheBoundaries };
 export type { KodaXAnthropicCacheableBlock, KodaXCacheLowerMode, KodaXRunScopedConfig, KodaXStopClass, RunVerifyCredentialOpts, SideQueryRequest, SideQueryResult, SideQueryStopReason, VerifyPrimitiveRunner };