@kodax-ai/kodax 0.7.76 → 0.7.78

package/dist/types-chunks/types-D3g6XUQr.d.ts

@@ -0,0 +1,662 @@
+import { k as KodaXMessage } from './types.d-DIpZJKUl.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;
+    /** Stable root-episode identity; absent on pre-F263 digests. */
+    readonly episodeId?: string;
+    readonly sessionId: string;
+    readonly branchId: string;
+    readonly sequence: number;
+    readonly objective: string;
+    readonly actionSignature?: string;
+    readonly approach: string;
+    /**
+     * `cancelled` is reserved for a host-bound explicit Memory intent. Ordinary
+     * cancelled episodes do not produce an outcome digest.
+     */
+    readonly outcome: 'succeeded' | 'failed' | 'cancelled';
+    readonly summary: string;
+    readonly preconditions?: string;
+    readonly lesson?: string;
+    readonly evidenceRefs: readonly string[];
+    readonly evidence?: readonly KodaXMemoryOutcomeEvidence[];
+    /**
+     * Explicit durable intent captured from the Action LLM and bound by the
+     * host to an exact quote in the current user turn. It is evidence for the
+     * governed reviewer, never proof that Memory was queued or applied.
+     */
+    readonly memoryIntent?: KodaXMemoryIntent;
+    readonly memoryInfluence?: readonly KodaXMemoryInfluenceRef[];
+    readonly visibility: 'prompt_safe' | 'private' | 'sensitive';
+    readonly createdAt: string;
+}
+interface KodaXMemoryIntent {
+    readonly operation: 'remember' | 'correct';
+    readonly evidenceRef: string;
+    /** Sanitized model-derived claim proposed for governed review. */
+    readonly candidateStatement: string;
+    /** Sanitized representation of the exact current-user quote verified by the host. */
+    readonly userQuote: string;
+}
+interface KodaXMemoryOutcomeEvidence {
+    readonly ref: string;
+    readonly grade: 'authoritative' | 'verified' | 'corroborated' | 'observed' | 'inferred';
+    readonly source: 'user' | 'host' | 'tool' | 'environment' | 'agent';
+    readonly verdict?: 'passed' | 'failed' | 'inconclusive';
+    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;
+    /** Durable F263 review job identity. Absent on pre-F263 lineage records. */
+    readonly jobId?: string;
+}
+interface KodaXSessionMemoryReviewReceiptEntry extends KodaXSessionEntryBase {
+    readonly type: 'memory_review_receipt';
+    /** Distinguishes repeated review keys across branch epochs. */
+    readonly jobId?: string;
+    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 {
+    /** Explicit owner home for durable runtime state; never persisted in review envelopes. */
+    readonly configHome?: string;
+    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' | 'intervention';
+}
+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>;
+    prepareEpisodeReview?(digest: KodaXMemoryOutcomeDigest): Promise<MemoryReviewModelInput>;
+    applyReviewedEpisode?(plan: MemoryReviewPlan, digest: KodaXMemoryOutcomeDigest, signal?: AbortSignal, revalidateAuthority?: () => Promise<void>): Promise<MemoryEpisodeReviewResult>;
+    persistReviewPlan(plan: MemoryReviewPlan): Promise<readonly string[]>;
+    /**
+     * Resolves which episode-review proposals were actually auto-applied by the
+     * governed host policy. Used to keep durable receipts complete while user
+     * notices remain truthful.
+     */
+    listHostAppliedEpisodeProposalIds?(proposalIds: readonly string[]): 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;
+};
+
+type MemoryEvidenceGrade = 'authoritative' | 'verified' | 'corroborated' | 'observed' | 'inferred';
+interface MemoryEvidenceRef {
+    readonly ref: string;
+    readonly requestedGrade: MemoryEvidenceGrade;
+    readonly source: 'user' | 'host' | 'tool' | 'environment' | 'agent';
+    readonly verdict?: 'passed' | 'failed' | 'inconclusive';
+    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;
+    readonly source?: 'current' | 'session' | 'durable';
+    readonly evidenceRefs?: readonly string[];
+}
+interface MemoryRecallRunnerInput {
+    readonly objective: string;
+    readonly decisionContext: string;
+    readonly decisionIntent: string;
+    readonly triggers?: readonly MemoryInterventionTrigger[];
+    readonly candidates: readonly MemoryRecallCandidate[];
+    readonly signal: AbortSignal;
+}
+type MemoryRecallRunner = (input: MemoryRecallRunnerInput) => Promise<{
+    readonly selectedRefIds: readonly string[];
+}>;
+type MemorySelectionMode = 'task_hint' | 'exact'
+/** @deprecated Retained for source compatibility; F275 no longer emits this mode. */
+ | 'semantic_prefetch' | 'semantic_intervention' | 'deliberate_query';
+type MemoryInterventionTrigger = 'tool_failure' | 'verification_failure' | 'context_compacted';
+interface MemoryInterventionInput extends MemoryRecallInput {
+    readonly triggers: readonly MemoryInterventionTrigger[];
+    readonly currentCandidates: readonly MemoryRecallCandidate[];
+    readonly signal?: AbortSignal;
+}
+interface MemoryDecisionReceipt {
+    readonly id: string;
+    readonly decisionEpoch: string;
+    readonly decisionRevision: string;
+    readonly policyVersion: string;
+    readonly candidateSetFingerprint: string;
+    /** Candidate identities offered to deterministic or semantic selection. */
+    readonly candidateIds: readonly string[];
+    /** Candidate identities selected after validating the runner output. */
+    readonly selectedCandidateIds: readonly string[];
+    /** Source evidence exposed to the Action LLM after deterministic rendering. */
+    readonly injectedEvidenceRefs: readonly string[];
+    readonly triggers?: readonly MemoryInterventionTrigger[];
+    /** @deprecated Use candidateIds. */
+    readonly candidateRefs: readonly string[];
+    /** @deprecated Use selectedCandidateIds. */
+    readonly selectedRefs: readonly string[];
+    /** @deprecated Use injectedEvidenceRefs. */
+    readonly injectedRefs: readonly string[];
+    readonly selectionModes: readonly MemorySelectionMode[];
+    readonly actionSignature?: string;
+    readonly throughSequence: number;
+}
+type MemoryAgentTraceEvent = {
+    readonly type: 'recall.intervention.failed' | 'recall.intervention.discarded'
+    /** @deprecated Retained for source compatibility; F275 no longer emits prefetch events. */
+     | 'recall.prefetch.completed'
+    /** @deprecated Retained for source compatibility; F275 no longer emits prefetch events. */
+     | 'recall.prefetch.failed'
+    /** @deprecated Retained for source compatibility; F275 no longer emits prefetch events. */
+     | 'recall.prefetch.discarded' | 'query.failed' | 'review.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;
+    /** Stable caller-owned identity for this root episode. */
+    readonly episodeId?: string;
+}
+interface MemoryEpisodeOutcome {
+    readonly status: 'succeeded' | 'failed' | 'cancelled';
+    readonly summary: string;
+    readonly evidence: readonly MemoryEvidenceRef[];
+    readonly memoryIntent?: KodaXMemoryIntent;
+}
+type PersistedOutcomeDigest = KodaXMemoryOutcomeDigest;
+interface MemorySession {
+    observe(observation: MemoryObservation): void;
+    recall(input: MemoryRecallInput): MemoryReminder | undefined;
+    intervene(input: MemoryInterventionInput): Promise<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;
+}
+
+export type { MemorySourcePolicy as A, CreateMemoryAgentOptions as C, KodaXSessionArtifactLedgerEntry as K, MemoryAgent as M, PersistedOutcomeDigest as P, KodaXSessionLineage as a, MemoryAgentTraceEvent as b, MemoryApplicability as c, MemoryContextIdentity as d, MemoryController as e, MemoryDecisionReceipt as f, MemoryEpisodeOutcome as g, MemoryEvent as h, MemoryEvidenceGrade as i, MemoryEvidenceRef as j, MemoryInterventionInput as k, MemoryInterventionTrigger as l, MemoryItemRef as m, MemoryObservation as n, MemoryObservationKind as o, MemoryPack as p, MemoryQueryInput as q, MemoryRecallCandidate as r, MemoryRecallInput as s, MemoryRecallRunner as t, MemoryRecallRunnerInput as u, MemoryReminder as v, MemoryReviewRunner as w, MemorySelectionMode as x, MemorySession as y, MemorySessionInput as z };