@inixiative/foundry-core 0.4.0 → 0.5.0

package/src/capability.ts

@@ -133,6 +133,41 @@ export interface GateContext {
   meta?: Record<string, unknown>;
 }
 
+/** The level a policy gives a capability, without prompting: what CapabilityGate checks. */
+export function permissionLevel(
+  policy: PermissionPolicy,
+  capability: Capability,
+  ctx?: Partial<GateContext>,
+): PermissionLevel {
+  const explicit = policy.capabilities[capability];
+
+  // Protected paths always hold: an explicit allow for the capability never switches them off.
+  if (
+    explicit !== 'deny' &&
+    (capability === 'file:write' || capability === 'file:delete') &&
+    policy.protectedPaths?.length &&
+    typeof ctx?.meta?.path === 'string'
+  ) {
+    const path = ctx.meta.path;
+    if (policy.protectedPaths.some((p) => path.includes(p))) return 'prompt';
+  }
+
+  if (explicit) return explicit;
+
+  // Cost threshold check for LLM calls
+  if (
+    capability === 'llm:call' &&
+    policy.costThreshold != null &&
+    ctx?.meta?.estimatedCost != null
+  ) {
+    if ((ctx.meta.estimatedCost as number) > policy.costThreshold) {
+      return 'prompt';
+    }
+  }
+
+  return policy.defaults;
+}
+
 export class CapabilityGate {
   private _policy: PermissionPolicy;
   private _queue: ActionQueue;
@@ -201,34 +236,7 @@ export class CapabilityGate {
   // -- Internal --
 
   private _resolve(capability: Capability, ctx?: GateContext): PermissionLevel {
-    // Explicit capability override
-    const explicit = this._policy.capabilities[capability];
-    if (explicit) return explicit;
-
-    // Cost threshold check for LLM calls
-    if (
-      capability === 'llm:call' &&
-      this._policy.costThreshold != null &&
-      ctx?.meta?.estimatedCost != null
-    ) {
-      if ((ctx.meta.estimatedCost as number) > this._policy.costThreshold) {
-        return 'prompt';
-      }
-    }
-
-    // Protected paths check for file ops
-    if (
-      (capability === 'file:write' || capability === 'file:delete') &&
-      this._policy.protectedPaths?.length &&
-      ctx?.meta?.path
-    ) {
-      const path = ctx.meta.path as string;
-      if (this._policy.protectedPaths.some((p) => path.includes(p))) {
-        return 'prompt';
-      }
-    }
-
-    return this._policy.defaults;
+    return permissionLevel(this._policy, capability, ctx);
   }
 
   private _buildMessage(capability: Capability, ctx: GateContext): string {

package/src/context-layer.ts

@@ -53,6 +53,8 @@ export interface SourceLoadHint {
  * automatic selection, never a substitute for the retained log.
  */
 export interface SourceSelectionReport {
+  /** What the records are. Absent: memory records. */
+  readonly subject?: 'memory' | 'instructions';
   readonly selected: Array<{
     readonly id: string;
     readonly reason: string;
@@ -69,6 +71,8 @@ export interface SourceSelectionReport {
     readonly chars: number;
     readonly kind?: string;
     readonly excludedFor?: LogicalMessageIdentity;
+    /** The copy kept in its place, for a record left out as a duplicate. */
+    readonly duplicateOf?: string;
   }>;
   /** Records the reader was allowed to see. */
   readonly considered: number;
@@ -99,6 +103,12 @@ export interface ContextSource {
   readonly focusable?: boolean;
   /** The selection report of the last load, when this source selects rather than dumps. */
   report?(): SourceSelectionReport | undefined;
+  /**
+   * True when what the last load read has changed since (an edited or added file). The owning warm
+   * layer then turns stale on its next staleness check, without waiting out its staleness window.
+   * Must be cheap: it runs before every assembly.
+   */
+  changed?(): boolean;
 }
 
 /** Selection provenance carried on a layer instance for inspection. */
@@ -265,6 +275,11 @@ export interface ContextLayerConfig {
   prompt?: string;
   /** Semantic segment of the content; overrides the definition's segment when given. */
   segment?: LayerSegment;
+  /**
+   * Content that changes nearly every turn (the Librarian's thread state). A session provider
+   * sends it with each turn and never holds it in a session's standing context.
+   */
+  perTurn?: boolean;
 }
 
 export type LayerState = 'cold' | 'warming' | 'warm' | 'stale' | 'compressing';
@@ -301,6 +316,9 @@ export class ContextLayer {
    */
   readonly segment: LayerSegment | undefined;
 
+  /** Sent with each turn, never part of a session's standing context (`ContextLayerConfig.perTurn`). */
+  readonly perTurn: boolean;
+
   private _content: string = '';
   private _state: LayerState = 'cold';
   private _hash: string = '';
@@ -338,6 +356,7 @@ export class ContextLayer {
     if (segment !== undefined && !isLayerSegment(segment))
       throw new Error(`Unknown layer segment "${String(segment)}" for layer "${config.id}"`);
     this.segment = segment;
+    this.perTurn = config.perTurn ?? false;
   }
 
   // -- Factory --
@@ -397,6 +416,7 @@ export class ContextLayer {
       maxTokens: this._maxTokens,
       prompt: this._prompt,
       segment: this.segment,
+      perTurn: this.perTurn,
     });
     copy._focus = this._focus;
     copy._currentMessage = this._currentMessage;
@@ -485,19 +505,37 @@ export class ContextLayer {
     return this._state;
   }
 
-  /** Check if this layer has become stale. Triggers state transition if so. */
+  /**
+   * Check if this layer has become stale: its staleness window passed, or a source reports that
+   * what it read has changed. Triggers the state transition if so.
+   */
   checkStaleness(): LayerState {
     if (
       this._state === 'warm' &&
-      this._staleness !== undefined &&
-      this._lastWarmed !== null &&
-      Date.now() - this._lastWarmed > this._staleness
+      ((this._staleness !== undefined &&
+        this._lastWarmed !== null &&
+        Date.now() - this._lastWarmed > this._staleness) ||
+        this._sources.some((source) => source.changed?.()))
     ) {
       this._setState('stale');
     }
     return this._state;
   }
 
+  /**
+   * Whether assembly includes this layer: warm, or stale or re-warming with content that does not
+   * depend on the message (no focusable source). A standing layer keeps its last content until a
+   * re-warm completes, so it never drops out of context while one is slow or in flight.
+   */
+  get assemblable(): boolean {
+    return (
+      this._state === 'warm' ||
+      ((this._state === 'stale' || this._state === 'warming') &&
+        this._lastWarmed !== null &&
+        !this._sources.some((source) => source.focusable))
+    );
+  }
+
   get hash(): string {
     return this._hash;
   }

package/src/context-stack.ts

@@ -36,6 +36,13 @@ export interface PromptBlock {
   readonly segment?: string;
   /** Who produced this block (a domain, the router, a layer id). */
   readonly source?: string;
+  /**
+   * "after-message": a per-turn note appended to the end of the user's message rather than placed
+   * in the context (a Warden chiming in). Default: in the context.
+   */
+  readonly placement?: 'after-message';
+  /** From a per-turn layer: sent with each turn, never held as standing context. */
+  readonly perTurn?: true;
 }
 
 /** Structured prompt assembled from agent prompt + layer prompts + layer content. */
@@ -141,7 +148,7 @@ export class ContextStack {
   merge(filter?: LayerFilter): string {
     const layers = filter ? this._layers.filter(filter) : this._layers;
     return layers
-      .filter((l) => l.isWarm && l.content.length > 0)
+      .filter((l) => l.assemblable && l.content.length > 0)
       .map((l) => l.content)
       .join('\n\n');
   }
@@ -171,11 +178,12 @@ export class ContextStack {
     const layers = filter ? this._layers.filter(filter) : this._layers;
 
     for (const layer of layers) {
-      if (!layer.isWarm || layer.content.length === 0) continue;
+      if (!layer.assemblable || layer.content.length === 0) continue;
+      const perTurn = layer.perTurn ? { perTurn: true as const } : {};
 
       if (layer.prompt) {
         // A layer prompt is always an instruction; it never inherits the content segment.
-        blocks.push({ role: 'layer', id: layer.id, text: layer.prompt });
+        blocks.push({ role: 'layer', id: layer.id, text: layer.prompt, ...perTurn });
       }
       // The content block carries the layer's declared segment when it has one; legacy
       // layers leave it unset and the artifact builder falls back to its id heuristic.
@@ -184,6 +192,7 @@ export class ContextStack {
         id: layer.id,
         text: layer.content,
         ...(layer.segment ? { segment: layer.segment } : {}),
+        ...perTurn,
       });
     }
 
@@ -197,7 +206,7 @@ export class ContextStack {
     const content = this.merge();
     const layerHashes: Record<string, string> = {};
     for (const layer of this._layers) {
-      if (layer.isWarm) {
+      if (layer.assemblable) {
         layerHashes[layer.id] = layer.hash;
       }
     }

package/src/executor.ts

@@ -3,6 +3,11 @@ import { computeHash, REQUIRED_CONTEXT_BLOCKED } from './context-layer';
 import type { AssembledContext, ContextStack, LayerFilter } from './context-stack';
 import { buildInjectionArtifact, type InjectionArtifact, type MessageDecoration } from './messages';
 import type { NativeEvidence, NativeObservation } from './native-evidence';
+import {
+  type SessionDelivery,
+  type SessionDeliveryReport,
+  standingParts,
+} from './session-delivery';
 import type { ToolCallObservation } from './tools';
 import type { LLMMessage } from './types';
 
@@ -39,6 +44,10 @@ export interface ExecuteMeta {
   recordProviderInput?: (messages: LLMMessage[]) => void;
   /** Capture prepared input even on failure; this is not delivery acknowledgment. */
   recordInjection?: (artifact: InjectionArtifact) => void;
+  /** The context split for a session provider; set by the executor for its handler. */
+  delivery?: SessionDelivery;
+  /** The handler reports what a session provider delivered (CompletionResult.delivery). */
+  recordDelivery?: (report: SessionDeliveryReport) => void;
 }
 
 export type ExecuteHandler<TPayload, TResult> = (
@@ -77,8 +86,17 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
     const decoration = meta?.annotations?.decoration as MessageDecoration | undefined;
     const plan = meta?.annotations?.injectionPlan;
     const base = this.assembleContext(filterOverride);
-    const blocks = decoration?.blocks.length ? [...base.blocks, ...decoration.blocks] : base.blocks;
-    const assembled: AssembledContext = decoration?.blocks.length
+    // Notes placed after the message (Wardens chiming in) end the user's turn; the rest is context.
+    // A payload that is not text has no end to append to; its notes stay in the context.
+    const appendable = typeof payload === 'string';
+    const contextual = (decoration?.blocks ?? []).filter(
+      (b) => !appendable || b.placement !== 'after-message',
+    );
+    const notes = appendable
+      ? (decoration?.blocks ?? []).filter((b) => b.placement === 'after-message')
+      : [];
+    const blocks = contextual.length ? [...base.blocks, ...contextual] : base.blocks;
+    const assembled: AssembledContext = contextual.length
       ? { blocks, text: blocks.map((block) => block.text).join('\n\n') }
       : base;
     const context = assembled.text;
@@ -107,7 +125,18 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
         ]),
       ),
     });
+    // The same context split for session providers: standing parts (the assembled layers) and the
+    // per-turn text (per-turn layers, then the decoration). `heldLayers` is the thread's delivery
+    // ledger, set by the flow middleware.
+    const delivery: SessionDelivery = {
+      standing: standingParts(base.blocks.filter((block) => !block.perTurn)),
+      turn: [...base.blocks.filter((block) => block.perTurn), ...contextual]
+        .map((block) => block.text)
+        .join('\n\n'),
+      held: { ...((meta?.annotations?.heldLayers as Record<string, string> | undefined) ?? {}) },
+    };
     let providerMessages: LLMMessage[] | undefined;
+    let sessionDelivery: SessionDeliveryReport | undefined;
     let providerBoundary: ProviderBoundaryReceipt | undefined;
     const capture = (): InjectionArtifact => ({
       ...injection,
@@ -118,6 +147,8 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
       providerBoundary,
       executorContext: context,
       providerMessages,
+      ...(sessionDelivery ? { sessionDelivery } : {}),
+      standingParts: delivery.standing.map(({ id, hash }) => ({ id, hash })),
       layers,
       ...(plan !== undefined ? { plan } : {}),
     });
@@ -137,6 +168,9 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
     // selection. No retry/replay is implied by refusing this provider call.
     const mismatched = layers.filter((layer) => {
       if (!layer.included || !layer.selection) return false;
+      // A composition report (instruction files) is not a per-message selection.
+      if (layer.selection.sources.every((source) => source.report.subject === 'instructions'))
+        return false;
       const selectedFor = layer.selection.currentMessage;
       // Standalone legacy sources have no request-identity contract. A flow
       // plan does: even its unidentified loads must not replace identified work.
@@ -177,8 +211,17 @@ export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<T
     let native: NativeEvidence | undefined;
     let recording = true;
     try {
-      output = await this._handler(context, payload, {
+      const sent = (
+        notes.length && typeof payload === 'string'
+          ? `${payload}\n\n---\n\n${notes.map((note) => note.text).join('\n\n')}`
+          : payload
+      ) as TPayload;
+      output = await this._handler(context, sent, {
         ...meta,
+        delivery,
+        recordDelivery: (report) => {
+          sessionDelivery = structuredClone(report);
+        },
         recordNative: (evidence) => {
           if (recording) {
             native = evidence;