@odla-ai/harness 0.2.0 → 0.4.0

package/dist/node.d.cts

@@ -2,7 +2,7 @@ import { r as HarnessTaskSpec, g as HarnessAgentOutput, f as HarnessAgentInput,
 import { CodePortableCheckpoint, CodeSourceFile, CodeVerificationReceipt, CodeCheckpointState } from '@odla-ai/camel/code';
 import { Skill, Inference, AgentRunBudget, AgentRun, CompactionPolicy } from '@odla-ai/ai';
 import { PolicyOutcome } from '@odla-ai/camel/policy';
-import { PartitionVerdict } from '@odla-ai/graph';
+import { Graph, PartitionVerdict } from '@odla-ai/graph';
 
 /** Supported command-line container engines for isolated harness attempts. */
 type ContainerEngine = "container" | "podman" | "docker";
@@ -243,9 +243,44 @@ interface CodeRuntimeAgentControlPlane extends CodeRuntimeControlPlane {
     infer(sessionId: string, request: HarnessInferenceRequest): Promise<HarnessInferenceResponse>;
     review(sessionId: string, request: CodeRuntimeReviewRequest): Promise<CodeRuntimeReviewResponse>;
     submitCandidate(sessionId: string, checkpointId: string, verification: CodeVerificationReceipt): Promise<CodeRuntimeCandidateResponse>;
+    /**
+     * Agent memory, brokered like inference is.
+     *
+     * Optional so an older control plane still satisfies the interface — a Code
+     * host talking to a registry that predates memory should lose the feature,
+     * not the session.
+     */
+    recallMemories?(sessionId: string, subjects: readonly string[], limit: number): Promise<CodeRuntimeMemory[]>;
+    rememberMemory?(sessionId: string, memory: CodeRuntimeNewMemory): Promise<void>;
     appendSessionEvent(sessionId: string, eventId: string, event: CodeSessionEventData): Promise<void>;
     reportSessionFailure(sessionId: string, message: string): Promise<void>;
 }
+/** One memory as the control plane returns it. */
+interface CodeRuntimeMemory {
+    id: string;
+    subject: string;
+    kind: string;
+    body: string;
+    evidence?: {
+        kind: string;
+        ref: string;
+    };
+    authorId: string;
+    createdAt: number;
+    supersededBy?: string;
+}
+/** A memory a run wants recorded. The author is set by the control plane. */
+interface CodeRuntimeNewMemory {
+    subject: string;
+    kind: string;
+    body: string;
+    evidence?: {
+        kind: string;
+        ref: string;
+    };
+    /** Idempotency key, so a retried write records once. */
+    mutationId: string;
+}
 /** Untrusted candidate material available only to the independent review route. */
 interface CodeRuntimeReviewRequest {
     patch: string;
@@ -687,6 +722,164 @@ interface CodeRuntimeInferenceOptions {
  */
 declare function createCodeRuntimeInference(options: CodeRuntimeInferenceOptions): Inference;
 
+/** What kind of thing was learned. */
+type CodeMemoryKind = 
+/** An approach that failed, and what the gate said about it. */
+"hazard"
+/** Something true of this codebase that reading it does not reveal. */
+ | "invariant"
+/** What a goal actually achieved, judged by a verifier rather than claimed. */
+ | "outcome"
+/** Everything else worth carrying forward. */
+ | "note";
+/**
+ * What produced a memory.
+ *
+ * This field is what stops a shared store becoming a rumour mill. An agent that
+ * can write unfalsifiable claims into memory poisons every run that follows, so
+ * a finding carries the thing that produced it and a bare assertion is visibly
+ * a lesser class of claim.
+ */
+interface CodeMemoryEvidence {
+    kind: "gate" | "receipt" | "human";
+    /** A verification id, a receipt digest, or a person. */
+    ref: string;
+}
+/** One thing the agent learned about this codebase. */
+interface CodeMemory {
+    id: string;
+    /** A graph node id — `file:src/a.ts`, `table:orders`, `symbol:runAgent`. */
+    subject: string;
+    kind: CodeMemoryKind;
+    body: string;
+    evidence?: CodeMemoryEvidence;
+    /** Principal that recorded it. Attributed, never authenticated — see PM. */
+    authorId: string;
+    createdAt: number;
+    /** Set when a later memory contradicts this one. */
+    supersededBy?: string;
+}
+/** A memory before it has an id or a timestamp. */
+type NewCodeMemory = Omit<CodeMemory, "id" | "createdAt">;
+/**
+ * Where memories live.
+ *
+ * An interface rather than a database, because a Code host holds no tenant
+ * credential — the same reason inference is brokered. The control plane
+ * supplies the implementation; the agent only ever sees this.
+ */
+interface CodeMemoryStore {
+    /** Memories about any of these subjects, newest first. */
+    recall(subjects: readonly string[], limit: number): Promise<CodeMemory[]>;
+    remember(memory: NewCodeMemory): Promise<CodeMemory>;
+}
+/** Longest body worth storing. A memory is a lesson, not a transcript. */
+declare const MAX_MEMORY_BODY = 4000;
+/** Reject a memory that would be useless or unbounded before it is stored. */
+declare function validateMemory(memory: NewCodeMemory): void;
+/** How wide to cast when gathering what is known about some subjects. */
+interface RecallOptions {
+    /**
+     * Also recall memories about what the subjects reach.
+     *
+     * A hazard recorded against a module matters to everything that imports it,
+     * and the whole reason subjects are graph ids is that this is one traversal.
+     * Off by default: the neighbourhood of a hub is most of the repository.
+     */
+    graph?: Graph;
+    /** Edge kinds to spread across when `graph` is given. */
+    kinds?: readonly string[];
+    /** How far to spread. Default 1 — direct neighbours only. */
+    depth?: number;
+    /** Cap on returned memories. Default 20. */
+    limit?: number;
+}
+/**
+ * Gather what is known about some subjects, optionally including their
+ * neighbourhood.
+ *
+ * Superseded memories are dropped. Keeping them would mean the agent reads a
+ * correction and its own contradiction in the same breath, and has to guess
+ * which is current — which is worse than not remembering at all.
+ */
+declare function recallAbout(store: CodeMemoryStore, subjects: readonly string[], options?: RecallOptions): Promise<CodeMemory[]>;
+/** Render memories for a prompt — the cheapest form that still says enough. */
+declare function renderMemories(memories: readonly CodeMemory[]): string;
+/**
+ * Turn a failed attempt into something the next run does not have to pay for.
+ *
+ * This is the write that justifies the store. The gate's verdict is the most
+ * expensive knowledge a run produces — it cost a whole attempt — and until now
+ * it was dropped the moment the next prompt was built.
+ *
+ * Recorded against the files the attempt actually touched, so it surfaces to
+ * whoever works on them next rather than being filed under the goal, which
+ * nobody will ever search for.
+ */
+declare function hazardFromAttempt(input: {
+    goal: string;
+    attempt: number;
+    feedback: string;
+    touched: readonly string[];
+    verificationId: string;
+    authorId: string;
+}): NewCodeMemory[];
+
+/**
+ * Present a session's brokered memory as a store, or null when the control
+ * plane does not offer one.
+ *
+ * Null rather than a throwing stub: a Code host talking to a registry that
+ * predates memory should quietly lose the feature, not fail every goal that
+ * would have recorded something.
+ */
+declare function runtimeMemoryStore(control: CodeRuntimeAgentControlPlane, sessionId: string): CodeMemoryStore | null;
+
+/** What a run actually did, judged rather than claimed. */
+interface GoalOutcome {
+    /** The PM entity this goal came from, when it came from one. */
+    pmEntityId?: string;
+    goal: string;
+    /** How the goal said it would be judged. */
+    proof: string;
+    /** Whether the clean verifier agreed. */
+    met: boolean;
+    /** Why it stopped — `proof_passed`, or the budget that ran out. */
+    stoppedReason: string;
+    attempts: number;
+    tokens: number;
+    costUsd?: number;
+    /** The receipt that backs a met verdict. Absent means nothing backs it. */
+    evidence?: CodeMemoryEvidence;
+}
+/**
+ * Whether an outcome may move a PM item to done.
+ *
+ * Two conditions, and the second is the one that matters: the verifier agreed,
+ * AND it left a receipt. A `met` with no evidence is an agent's assertion
+ * wearing a verdict's clothes, and admitting it would make the whole audit
+ * trail decorative.
+ */
+declare function outcomeCloses(outcome: GoalOutcome): boolean;
+/**
+ * Say plainly what happened, for the PM comment that records it.
+ *
+ * Written for a human deciding whether to trust the result, so the numbers that
+ * bound the claim — attempts, tokens, cost — are in the sentence rather than in
+ * a linked artifact nobody opens. Unknown cost is said as unknown; reporting
+ * $0.00 for a run whose pricing was unavailable would be a lie in the direction
+ * that flatters the agent.
+ */
+declare function renderOutcome(outcome: GoalOutcome): string;
+/**
+ * Record the outcome as a memory, so the next run knows what this one settled.
+ *
+ * Filed against the goal's subject rather than a file: an outcome is about an
+ * intention, and the useful question later is "has anyone tried this before",
+ * not "what happened to line 40".
+ */
+declare function outcomeMemory(outcome: GoalOutcome, subject: string, authorId: string): NewCodeMemory;
+
 /** Everything the runner learns from one attempt. */
 interface GoalAttemptOutcome {
     /** Did the goal's proof pass on the resulting tree? */
@@ -1122,4 +1315,4 @@ interface CodeVerificationEvidence {
 /** Rebuild a candidate from an exact trusted base and emit a prose-free clean-verifier receipt. */
 declare function verifyCodeCandidate(input: VerifyCodeCandidateInput): Promise<CodeVerificationEvidence>;
 
-export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeAgentAttemptOptions, type CodeAgentAttemptResult, type CodeAgentRun, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeInferenceOptions, type CodeRuntimeLoopOptions, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeSkillOpts, type CodeSurface, type CodeToolBrokerOptions, type CodeToolCallRecord, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type DecomposedRun, DecompositionError, type GoalAttempt, type GoalAttemptInput, type GoalAttemptOutcome, type GoalAttemptRecord, type GoalBudget, type GoalEvent, type GoalRun, type GoalRunSpec, type GoalStoppedReason, type GoalStrategy, type HarnessRunnerOptions, type IntegrateOptions, type IntegrationStep, MEASURED_PREMIUM, type MaterializedCodeSource, type MaterializedGitTree, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RacedAttemptOptions, type RacedOutcome, type RecipeDependencies, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RunCodeAgentOptions, type RuntimeCheckpointSession, SYSTEM_PROMPT_FOR, type StageWorkspaceOptions, type StagedWorkspace, type StrategyChoice, type StrategySignals, type SubGoal, type SubGoalResult, V1_SYSTEM_PROMPT, V2_SYSTEM_PROMPT, V3_SYSTEM_PROMPT, type VerifyCodeCandidateInput, applyCodePatch, assertCodeBuildRecipe, assertDisjointPlan, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, chooseStrategy, codeSkill, createCodeRuntimeControlClient, createCodeRuntimeInference, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, describePatchFailure, digestStagedWorkspace, feedbackIsActionable, installedDependencies, integrateSubGoals, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeCommandWorkspace, materializeGitTree, patchPaths, planReachCollisions, prepareRuntimeCheckpoint, racedAttempt, registeredFiles, resolveCodePath, restoreCodeWorkspaceCheckpoint, runCodeAgent, runCodeAgentAttempt, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runGoal, runHarnessRunner, runLeasedAttempt, safeWorkspaceLabel, selectContainerEngine, selectWinner, stageWorkspace, stageWorkspacePair, straySubGoalFiles, stripPatchEnvelope, validateCodePatch, validateRelativePath, verifyCodeCandidate, verifyContainerEngineBoundary, withRecipeDependencies };
+export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeAgentAttemptOptions, type CodeAgentAttemptResult, type CodeAgentRun, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, type CodeMemory, type CodeMemoryEvidence, type CodeMemoryKind, type CodeMemoryStore, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeInferenceOptions, type CodeRuntimeLoopOptions, type CodeRuntimeMemory, type CodeRuntimeNewMemory, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeSkillOpts, type CodeSurface, type CodeToolBrokerOptions, type CodeToolCallRecord, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type DecomposedRun, DecompositionError, type GoalAttempt, type GoalAttemptInput, type GoalAttemptOutcome, type GoalAttemptRecord, type GoalBudget, type GoalEvent, type GoalOutcome, type GoalRun, type GoalRunSpec, type GoalStoppedReason, type GoalStrategy, type HarnessRunnerOptions, type IntegrateOptions, type IntegrationStep, MAX_MEMORY_BODY, MEASURED_PREMIUM, type MaterializedCodeSource, type MaterializedGitTree, type NewCodeMemory, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RacedAttemptOptions, type RacedOutcome, type RecallOptions, type RecipeDependencies, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RunCodeAgentOptions, type RuntimeCheckpointSession, SYSTEM_PROMPT_FOR, type StageWorkspaceOptions, type StagedWorkspace, type StrategyChoice, type StrategySignals, type SubGoal, type SubGoalResult, V1_SYSTEM_PROMPT, V2_SYSTEM_PROMPT, V3_SYSTEM_PROMPT, type VerifyCodeCandidateInput, applyCodePatch, assertCodeBuildRecipe, assertDisjointPlan, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, chooseStrategy, codeSkill, createCodeRuntimeControlClient, createCodeRuntimeInference, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, describePatchFailure, digestStagedWorkspace, feedbackIsActionable, hazardFromAttempt, installedDependencies, integrateSubGoals, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeCommandWorkspace, materializeGitTree, outcomeCloses, outcomeMemory, patchPaths, planReachCollisions, prepareRuntimeCheckpoint, racedAttempt, recallAbout, registeredFiles, renderMemories, renderOutcome, resolveCodePath, restoreCodeWorkspaceCheckpoint, runCodeAgent, runCodeAgentAttempt, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runGoal, runHarnessRunner, runLeasedAttempt, runtimeMemoryStore, safeWorkspaceLabel, selectContainerEngine, selectWinner, stageWorkspace, stageWorkspacePair, straySubGoalFiles, stripPatchEnvelope, validateCodePatch, validateMemory, validateRelativePath, verifyCodeCandidate, verifyContainerEngineBoundary, withRecipeDependencies };

package/dist/node.d.ts

@@ -2,7 +2,7 @@ import { r as HarnessTaskSpec, g as HarnessAgentOutput, f as HarnessAgentInput,
 import { CodePortableCheckpoint, CodeSourceFile, CodeVerificationReceipt, CodeCheckpointState } from '@odla-ai/camel/code';
 import { Skill, Inference, AgentRunBudget, AgentRun, CompactionPolicy } from '@odla-ai/ai';
 import { PolicyOutcome } from '@odla-ai/camel/policy';
-import { PartitionVerdict } from '@odla-ai/graph';
+import { Graph, PartitionVerdict } from '@odla-ai/graph';
 
 /** Supported command-line container engines for isolated harness attempts. */
 type ContainerEngine = "container" | "podman" | "docker";
@@ -243,9 +243,44 @@ interface CodeRuntimeAgentControlPlane extends CodeRuntimeControlPlane {
     infer(sessionId: string, request: HarnessInferenceRequest): Promise<HarnessInferenceResponse>;
     review(sessionId: string, request: CodeRuntimeReviewRequest): Promise<CodeRuntimeReviewResponse>;
     submitCandidate(sessionId: string, checkpointId: string, verification: CodeVerificationReceipt): Promise<CodeRuntimeCandidateResponse>;
+    /**
+     * Agent memory, brokered like inference is.
+     *
+     * Optional so an older control plane still satisfies the interface — a Code
+     * host talking to a registry that predates memory should lose the feature,
+     * not the session.
+     */
+    recallMemories?(sessionId: string, subjects: readonly string[], limit: number): Promise<CodeRuntimeMemory[]>;
+    rememberMemory?(sessionId: string, memory: CodeRuntimeNewMemory): Promise<void>;
     appendSessionEvent(sessionId: string, eventId: string, event: CodeSessionEventData): Promise<void>;
     reportSessionFailure(sessionId: string, message: string): Promise<void>;
 }
+/** One memory as the control plane returns it. */
+interface CodeRuntimeMemory {
+    id: string;
+    subject: string;
+    kind: string;
+    body: string;
+    evidence?: {
+        kind: string;
+        ref: string;
+    };
+    authorId: string;
+    createdAt: number;
+    supersededBy?: string;
+}
+/** A memory a run wants recorded. The author is set by the control plane. */
+interface CodeRuntimeNewMemory {
+    subject: string;
+    kind: string;
+    body: string;
+    evidence?: {
+        kind: string;
+        ref: string;
+    };
+    /** Idempotency key, so a retried write records once. */
+    mutationId: string;
+}
 /** Untrusted candidate material available only to the independent review route. */
 interface CodeRuntimeReviewRequest {
     patch: string;
@@ -687,6 +722,164 @@ interface CodeRuntimeInferenceOptions {
  */
 declare function createCodeRuntimeInference(options: CodeRuntimeInferenceOptions): Inference;
 
+/** What kind of thing was learned. */
+type CodeMemoryKind = 
+/** An approach that failed, and what the gate said about it. */
+"hazard"
+/** Something true of this codebase that reading it does not reveal. */
+ | "invariant"
+/** What a goal actually achieved, judged by a verifier rather than claimed. */
+ | "outcome"
+/** Everything else worth carrying forward. */
+ | "note";
+/**
+ * What produced a memory.
+ *
+ * This field is what stops a shared store becoming a rumour mill. An agent that
+ * can write unfalsifiable claims into memory poisons every run that follows, so
+ * a finding carries the thing that produced it and a bare assertion is visibly
+ * a lesser class of claim.
+ */
+interface CodeMemoryEvidence {
+    kind: "gate" | "receipt" | "human";
+    /** A verification id, a receipt digest, or a person. */
+    ref: string;
+}
+/** One thing the agent learned about this codebase. */
+interface CodeMemory {
+    id: string;
+    /** A graph node id — `file:src/a.ts`, `table:orders`, `symbol:runAgent`. */
+    subject: string;
+    kind: CodeMemoryKind;
+    body: string;
+    evidence?: CodeMemoryEvidence;
+    /** Principal that recorded it. Attributed, never authenticated — see PM. */
+    authorId: string;
+    createdAt: number;
+    /** Set when a later memory contradicts this one. */
+    supersededBy?: string;
+}
+/** A memory before it has an id or a timestamp. */
+type NewCodeMemory = Omit<CodeMemory, "id" | "createdAt">;
+/**
+ * Where memories live.
+ *
+ * An interface rather than a database, because a Code host holds no tenant
+ * credential — the same reason inference is brokered. The control plane
+ * supplies the implementation; the agent only ever sees this.
+ */
+interface CodeMemoryStore {
+    /** Memories about any of these subjects, newest first. */
+    recall(subjects: readonly string[], limit: number): Promise<CodeMemory[]>;
+    remember(memory: NewCodeMemory): Promise<CodeMemory>;
+}
+/** Longest body worth storing. A memory is a lesson, not a transcript. */
+declare const MAX_MEMORY_BODY = 4000;
+/** Reject a memory that would be useless or unbounded before it is stored. */
+declare function validateMemory(memory: NewCodeMemory): void;
+/** How wide to cast when gathering what is known about some subjects. */
+interface RecallOptions {
+    /**
+     * Also recall memories about what the subjects reach.
+     *
+     * A hazard recorded against a module matters to everything that imports it,
+     * and the whole reason subjects are graph ids is that this is one traversal.
+     * Off by default: the neighbourhood of a hub is most of the repository.
+     */
+    graph?: Graph;
+    /** Edge kinds to spread across when `graph` is given. */
+    kinds?: readonly string[];
+    /** How far to spread. Default 1 — direct neighbours only. */
+    depth?: number;
+    /** Cap on returned memories. Default 20. */
+    limit?: number;
+}
+/**
+ * Gather what is known about some subjects, optionally including their
+ * neighbourhood.
+ *
+ * Superseded memories are dropped. Keeping them would mean the agent reads a
+ * correction and its own contradiction in the same breath, and has to guess
+ * which is current — which is worse than not remembering at all.
+ */
+declare function recallAbout(store: CodeMemoryStore, subjects: readonly string[], options?: RecallOptions): Promise<CodeMemory[]>;
+/** Render memories for a prompt — the cheapest form that still says enough. */
+declare function renderMemories(memories: readonly CodeMemory[]): string;
+/**
+ * Turn a failed attempt into something the next run does not have to pay for.
+ *
+ * This is the write that justifies the store. The gate's verdict is the most
+ * expensive knowledge a run produces — it cost a whole attempt — and until now
+ * it was dropped the moment the next prompt was built.
+ *
+ * Recorded against the files the attempt actually touched, so it surfaces to
+ * whoever works on them next rather than being filed under the goal, which
+ * nobody will ever search for.
+ */
+declare function hazardFromAttempt(input: {
+    goal: string;
+    attempt: number;
+    feedback: string;
+    touched: readonly string[];
+    verificationId: string;
+    authorId: string;
+}): NewCodeMemory[];
+
+/**
+ * Present a session's brokered memory as a store, or null when the control
+ * plane does not offer one.
+ *
+ * Null rather than a throwing stub: a Code host talking to a registry that
+ * predates memory should quietly lose the feature, not fail every goal that
+ * would have recorded something.
+ */
+declare function runtimeMemoryStore(control: CodeRuntimeAgentControlPlane, sessionId: string): CodeMemoryStore | null;
+
+/** What a run actually did, judged rather than claimed. */
+interface GoalOutcome {
+    /** The PM entity this goal came from, when it came from one. */
+    pmEntityId?: string;
+    goal: string;
+    /** How the goal said it would be judged. */
+    proof: string;
+    /** Whether the clean verifier agreed. */
+    met: boolean;
+    /** Why it stopped — `proof_passed`, or the budget that ran out. */
+    stoppedReason: string;
+    attempts: number;
+    tokens: number;
+    costUsd?: number;
+    /** The receipt that backs a met verdict. Absent means nothing backs it. */
+    evidence?: CodeMemoryEvidence;
+}
+/**
+ * Whether an outcome may move a PM item to done.
+ *
+ * Two conditions, and the second is the one that matters: the verifier agreed,
+ * AND it left a receipt. A `met` with no evidence is an agent's assertion
+ * wearing a verdict's clothes, and admitting it would make the whole audit
+ * trail decorative.
+ */
+declare function outcomeCloses(outcome: GoalOutcome): boolean;
+/**
+ * Say plainly what happened, for the PM comment that records it.
+ *
+ * Written for a human deciding whether to trust the result, so the numbers that
+ * bound the claim — attempts, tokens, cost — are in the sentence rather than in
+ * a linked artifact nobody opens. Unknown cost is said as unknown; reporting
+ * $0.00 for a run whose pricing was unavailable would be a lie in the direction
+ * that flatters the agent.
+ */
+declare function renderOutcome(outcome: GoalOutcome): string;
+/**
+ * Record the outcome as a memory, so the next run knows what this one settled.
+ *
+ * Filed against the goal's subject rather than a file: an outcome is about an
+ * intention, and the useful question later is "has anyone tried this before",
+ * not "what happened to line 40".
+ */
+declare function outcomeMemory(outcome: GoalOutcome, subject: string, authorId: string): NewCodeMemory;
+
 /** Everything the runner learns from one attempt. */
 interface GoalAttemptOutcome {
     /** Did the goal's proof pass on the resulting tree? */
@@ -1122,4 +1315,4 @@ interface CodeVerificationEvidence {
 /** Rebuild a candidate from an exact trusted base and emit a prose-free clean-verifier receipt. */
 declare function verifyCodeCandidate(input: VerifyCodeCandidateInput): Promise<CodeVerificationEvidence>;
 
-export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeAgentAttemptOptions, type CodeAgentAttemptResult, type CodeAgentRun, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeInferenceOptions, type CodeRuntimeLoopOptions, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeSkillOpts, type CodeSurface, type CodeToolBrokerOptions, type CodeToolCallRecord, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type DecomposedRun, DecompositionError, type GoalAttempt, type GoalAttemptInput, type GoalAttemptOutcome, type GoalAttemptRecord, type GoalBudget, type GoalEvent, type GoalRun, type GoalRunSpec, type GoalStoppedReason, type GoalStrategy, type HarnessRunnerOptions, type IntegrateOptions, type IntegrationStep, MEASURED_PREMIUM, type MaterializedCodeSource, type MaterializedGitTree, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RacedAttemptOptions, type RacedOutcome, type RecipeDependencies, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RunCodeAgentOptions, type RuntimeCheckpointSession, SYSTEM_PROMPT_FOR, type StageWorkspaceOptions, type StagedWorkspace, type StrategyChoice, type StrategySignals, type SubGoal, type SubGoalResult, V1_SYSTEM_PROMPT, V2_SYSTEM_PROMPT, V3_SYSTEM_PROMPT, type VerifyCodeCandidateInput, applyCodePatch, assertCodeBuildRecipe, assertDisjointPlan, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, chooseStrategy, codeSkill, createCodeRuntimeControlClient, createCodeRuntimeInference, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, describePatchFailure, digestStagedWorkspace, feedbackIsActionable, installedDependencies, integrateSubGoals, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeCommandWorkspace, materializeGitTree, patchPaths, planReachCollisions, prepareRuntimeCheckpoint, racedAttempt, registeredFiles, resolveCodePath, restoreCodeWorkspaceCheckpoint, runCodeAgent, runCodeAgentAttempt, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runGoal, runHarnessRunner, runLeasedAttempt, safeWorkspaceLabel, selectContainerEngine, selectWinner, stageWorkspace, stageWorkspacePair, straySubGoalFiles, stripPatchEnvelope, validateCodePatch, validateRelativePath, verifyCodeCandidate, verifyContainerEngineBoundary, withRecipeDependencies };
+export { CODE_RUNTIME_PROTOCOL_VERSION, type CodeAgentAttemptOptions, type CodeAgentAttemptResult, type CodeAgentRun, type CodeBuildRecipe, type CodeExpectedArtifact, type CodeLocalSourceDescriptor, type CodeMemory, type CodeMemoryEvidence, type CodeMemoryKind, type CodeMemoryStore, CodePiRuntimeEngine, type CodePiRuntimeEngineOptions, type CodeRecipeExecutor, type CodeRecipeResult, type CodeRuntimeAgentControlPlane, type CodeRuntimeBinding, type CodeRuntimeCandidateResponse, type CodeRuntimeCapabilities, CodeRuntimeCheckpointManager, type CodeRuntimeClientOptions, type CodeRuntimeCommand, type CodeRuntimeCommandEngine, type CodeRuntimeCommandKind, type CodeRuntimeCommandResult, CodeRuntimeControlError, type CodeRuntimeControlPlane, type CodeRuntimeInferenceOptions, type CodeRuntimeLoopOptions, type CodeRuntimeMemory, type CodeRuntimeNewMemory, CodeRuntimeReconciler, type CodeRuntimeReviewRequest, type CodeRuntimeReviewResponse, type CodeRuntimeSnapshot, type CodeRuntimeSourceSnapshot, type CodeSkillOpts, type CodeSurface, type CodeToolBrokerOptions, type CodeToolCallRecord, type CodeToolDecision, type CodeVerificationEvidence, type CodeVerificationLog, type CodeVerificationPolicy, type ContainerEngine, type ContainerEngineSelectionOptions, type ContainerEngineVerificationOptions, type ContainerLimits, type ContainerRunOptions, type ContainerRunResult, type CreateCodeWorkspaceCheckpointInput, type DecomposedRun, DecompositionError, type GoalAttempt, type GoalAttemptInput, type GoalAttemptOutcome, type GoalAttemptRecord, type GoalBudget, type GoalEvent, type GoalOutcome, type GoalRun, type GoalRunSpec, type GoalStoppedReason, type GoalStrategy, type HarnessRunnerOptions, type IntegrateOptions, type IntegrationStep, MAX_MEMORY_BODY, MEASURED_PREMIUM, type MaterializedCodeSource, type MaterializedGitTree, type NewCodeMemory, type PrepareRuntimeCheckpointInput, type PreparedRuntimeCheckpoint, type RacedAttemptOptions, type RacedOutcome, type RecallOptions, type RecipeDependencies, type RestoreCodeWorkspaceCheckpointInput, type RestoredCodeWorkspaceCheckpoint, type RunCodeAgentOptions, type RuntimeCheckpointSession, SYSTEM_PROMPT_FOR, type StageWorkspaceOptions, type StagedWorkspace, type StrategyChoice, type StrategySignals, type SubGoal, type SubGoalResult, V1_SYSTEM_PROMPT, V2_SYSTEM_PROMPT, V3_SYSTEM_PROMPT, type VerifyCodeCandidateInput, applyCodePatch, assertCodeBuildRecipe, assertDisjointPlan, assertPinnedImage, attachCodeRuntimeReferences, buildContainerRunArgs, buildRecipeContainerArgs, chooseStrategy, codeSkill, createCodeRuntimeControlClient, createCodeRuntimeInference, createCodeToolBroker, createCodeWorkspaceCheckpoint, createContainerRecipeExecutor, describePatchFailure, digestStagedWorkspace, feedbackIsActionable, hazardFromAttempt, installedDependencies, integrateSubGoals, isCheckpointEffectCompleted, materializeCodeRuntimeSource, materializeCommandWorkspace, materializeGitTree, outcomeCloses, outcomeMemory, patchPaths, planReachCollisions, prepareRuntimeCheckpoint, racedAttempt, recallAbout, registeredFiles, renderMemories, renderOutcome, resolveCodePath, restoreCodeWorkspaceCheckpoint, runCodeAgent, runCodeAgentAttempt, runCodeRuntimeHeartbeatLoop, runContainerAttempt, runGoal, runHarnessRunner, runLeasedAttempt, runtimeMemoryStore, safeWorkspaceLabel, selectContainerEngine, selectWinner, stageWorkspace, stageWorkspacePair, straySubGoalFiles, stripPatchEnvelope, validateCodePatch, validateMemory, validateRelativePath, verifyCodeCandidate, verifyContainerEngineBoundary, withRecipeDependencies };

package/dist/node.js

@@ -8,6 +8,7 @@ import {
   CodeRuntimeCheckpointManager,
   CodeRuntimeControlError,
   CodeRuntimeReconciler,
+  MAX_MEMORY_BODY,
   SYSTEM_PROMPT_FOR,
   V1_SYSTEM_PROMPT,
   V2_SYSTEM_PROMPT,
@@ -24,11 +25,14 @@ import {
   createContainerRecipeExecutor,
   describePatchFailure,
   digestStagedWorkspace,
+  hazardFromAttempt,
   isCheckpointEffectCompleted,
   materializeCodeRuntimeSource,
   materializeCommandWorkspace,
   prepareRuntimeCheckpoint,
+  recallAbout,
   registeredFiles,
+  renderMemories,
   resolveCodePath,
   restoreCodeWorkspaceCheckpoint,
   runCodeAgent,
@@ -37,9 +41,10 @@ import {
   runGoal,
   stripPatchEnvelope,
   validateCodePatch,
+  validateMemory,
   validateRelativePath,
   verifyCodeCandidate
-} from "./chunk-5FFR7U4L.js";
+} from "./chunk-ANNX7VGK.js";
 import {
   assertPinnedImage,
   buildContainerRunArgs,
@@ -54,6 +59,56 @@ import {
 import "./chunk-C5VQI2IF.js";
 import "./chunk-3QP4VDQS.js";
 
+// src/code-runtime-memory.ts
+async function mutationId(memory) {
+  const source = `${memory.subject} ${memory.kind} ${memory.body}`;
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(source));
+  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, 40);
+}
+function runtimeMemoryStore(control, sessionId) {
+  const recall = control.recallMemories;
+  const remember = control.rememberMemory;
+  if (!recall || !remember) return null;
+  return {
+    recall: async (subjects, limit) => await recall.call(control, sessionId, subjects, limit),
+    remember: async (memory) => {
+      await remember.call(control, sessionId, {
+        subject: memory.subject,
+        kind: memory.kind,
+        body: memory.body,
+        ...memory.evidence ? { evidence: memory.evidence } : {},
+        mutationId: await mutationId(memory)
+      });
+      return { ...memory, id: "", createdAt: Date.now() };
+    }
+  };
+}
+
+// src/code-goal-outcome.ts
+function outcomeCloses(outcome) {
+  return outcome.met && outcome.evidence !== void 0;
+}
+function renderOutcome(outcome) {
+  const spend = outcome.costUsd === void 0 ? "cost unknown" : `$${outcome.costUsd.toFixed(4)}`;
+  const scale = `${outcome.attempts} attempt(s), ${outcome.tokens.toLocaleString()} tokens, ${spend}`;
+  if (!outcome.met) {
+    return `Goal not met (${outcome.stoppedReason}) after ${scale}. Proof: ${outcome.proof}`;
+  }
+  if (!outcome.evidence) {
+    return `Goal reported met after ${scale}, but no verification receipt was produced. Treat as unverified. Proof: ${outcome.proof}`;
+  }
+  return `Goal met after ${scale}. Verified by ${outcome.evidence.kind}:${outcome.evidence.ref}. Proof: ${outcome.proof}`;
+}
+function outcomeMemory(outcome, subject, authorId) {
+  return {
+    subject,
+    kind: "outcome",
+    body: renderOutcome(outcome),
+    ...outcome.evidence ? { evidence: outcome.evidence } : {},
+    authorId
+  };
+}
+
 // src/code-goal-race.ts
 function selectWinner(outcomes) {
   const ranked = [...outcomes].sort((left, right) => {
@@ -311,6 +366,7 @@ export {
   CodeRuntimeControlError,
   CodeRuntimeReconciler,
   DecompositionError,
+  MAX_MEMORY_BODY,
   MEASURED_PREMIUM,
   SYSTEM_PROMPT_FOR,
   V1_SYSTEM_PROMPT,
@@ -333,17 +389,23 @@ export {
   describePatchFailure,
   digestStagedWorkspace,
   feedbackIsActionable,
+  hazardFromAttempt,
   installedDependencies,
   integrateSubGoals,
   isCheckpointEffectCompleted,
   materializeCodeRuntimeSource,
   materializeCommandWorkspace,
   materializeGitTree,
+  outcomeCloses,
+  outcomeMemory,
   patchPaths,
   planReachCollisions,
   prepareRuntimeCheckpoint,
   racedAttempt,
+  recallAbout,
   registeredFiles,
+  renderMemories,
+  renderOutcome,
   resolveCodePath,
   restoreCodeWorkspaceCheckpoint,
   runCodeAgent,
@@ -353,6 +415,7 @@ export {
   runGoal,
   runHarnessRunner,
   runLeasedAttempt,
+  runtimeMemoryStore,
   safeWorkspaceLabel,
   selectContainerEngine,
   selectWinner,
@@ -361,6 +424,7 @@ export {
   straySubGoalFiles,
   stripPatchEnvelope,
   validateCodePatch,
+  validateMemory,
   validateRelativePath,
   verifyCodeCandidate,
   verifyContainerEngineBoundary,