@inixiative/foundry-core 0.4.0 → 0.5.0

package/src/native-evidence.ts

@@ -167,7 +167,7 @@ export interface NativeBridgeLease {
   readonly toolPolicy?: NativeToolPolicy;
   /** Private, empty native cwd owned by a restricted fixture lease. */
   readonly fixtureCwd?: string;
-  readonly launch: { readonly claudeJson: string; readonly codexOverrides: readonly string[] };
+  readonly launch: { readonly claudeJson: string };
   check(): void;
   register(evidence: NativeEvidence): void;
   observe(evidence: NativeEvidence): void;
@@ -194,7 +194,17 @@ export interface NativeObservation {
   register(evidence: NativeEvidence): void | Promise<void>;
   /** Fallible observer; never vetoes executor completion. */
   observe(evidence: NativeEvidence): void | Promise<void>;
+  /** Receives the stop for this owner's registered admission, where the runtime acknowledges stops. */
+  interruptible?(interrupt: NativeInterrupt): void;
+  /**
+   * The executor's public thinking text, for live display only. It never becomes evidence:
+   * nothing here is journalled, traced or projected (reasoning stays out of NativeEvidence).
+   */
+  thought?(text: string): void;
 }
+/** `acknowledged`: the runtime confirmed the stop and the turn reached its native terminal. */
+export type NativeInterruptOutcome = 'acknowledged' | 'no-turn' | 'unacknowledged';
+export type NativeInterrupt = (opts?: { timeoutMs?: number }) => Promise<NativeInterruptOutcome>;
 export function freezeEvidence<T>(value: T): T {
   const copy = structuredClone(value);
   const freeze = (v: unknown) => {

package/src/scope.ts

@@ -9,6 +9,8 @@
 export interface OwnershipScope {
   readonly threadId?: string;
   readonly projectId?: string;
+  /** Where the thread's native session runs. Not ownership: sources that read the workspace resolve against it. */
+  readonly cwd?: string;
 }
 
 /** Copy a scope, dropping undefined fields so equality checks are stable. */

package/src/session-delivery.ts

@@ -0,0 +1,76 @@
+import { computeHash } from './context-layer';
+import type { PromptBlock } from './context-stack';
+
+/** One standing part of a thread's context (a layer with its prompt, or the agent's own prompt), keyed by content hash. */
+export interface StandingPart {
+  readonly id: string;
+  readonly hash: string;
+  readonly text: string;
+}
+
+/**
+ * A turn's context split for a provider that keeps a native session. Standing parts go into the
+ * session's system prompt once, when the session starts; afterwards only parts whose hash differs
+ * from what the session holds are sent with the turn. The per-turn text is sent every turn.
+ */
+export interface SessionDelivery {
+  /** Every standing part, in context order. */
+  readonly standing: readonly StandingPart[];
+  /** Per-turn context (routing, Warden advice); sent with every turn. */
+  readonly turn: string;
+  /**
+   * The thread's delivery ledger: part id → hash the session holds from an earlier turn's message.
+   * Cleared on compaction, reset when a session starts.
+   */
+  readonly held: Readonly<Record<string, string>>;
+}
+
+export interface DeliveredPart {
+  readonly id: string;
+  readonly hash: string;
+}
+
+/** What a session provider actually delivered for one turn. */
+export interface SessionDeliveryReport {
+  /** "started": this turn ran on a session that started with `base` as its system prompt. */
+  readonly session: 'started' | 'held';
+  /** The parts the session's system prompt carries. */
+  readonly base: readonly DeliveredPart[];
+  /** Standing parts sent in this turn's message because the session did not hold their hash. */
+  readonly sent: readonly DeliveredPart[];
+  /**
+   * A started session that resumed the conversation the thread's ledger describes (a relaunch in
+   * this process): the ledger still holds, so it is kept and extended rather than reset.
+   */
+  readonly ledgerKept?: true;
+}
+
+/** Group assembled layer blocks (a layer's prompt block, then its content block) into standing parts. */
+export function standingParts(blocks: readonly PromptBlock[]): StandingPart[] {
+  const parts: Array<{ id: string; texts: string[] }> = [];
+  for (const block of blocks) {
+    const id = block.id ?? `${block.role}:${parts.length}`;
+    const last = parts.at(-1);
+    if (last && last.id === id) last.texts.push(block.text);
+    else parts.push({ id, texts: [block.text] });
+  }
+  // Two layers may share an id (a configured layer and a runtime-owned one); each is its own part.
+  const seen = new Map<string, number>();
+  return parts.map(({ id, texts }) => {
+    const n = (seen.get(id) ?? 0) + 1;
+    seen.set(id, n);
+    return standingPart(n === 1 ? id : `${id}#${n}`, texts.join('\n\n'));
+  });
+}
+
+/** A warm layer as the standing part the executor assembles: its prompt, then its content. */
+export function layerPart(layer: { id: string; prompt?: string; content: string }): StandingPart {
+  return standingPart(
+    layer.id,
+    layer.prompt ? `${layer.prompt}\n\n${layer.content}` : layer.content,
+  );
+}
+
+export function standingPart(id: string, text: string): StandingPart {
+  return { id, hash: computeHash(text), text };
+}

package/src/thread.ts

@@ -125,6 +125,14 @@ export interface DispatchOptions {
   messageId?: string;
   /** How the caller invoked the agent: always, conditional, on-demand, background. */
   invocation?: string;
+  /**
+   * What the agent itself receives when it differs from the payload that middleware and the
+   * dispatch observation read: a host's instruction wrappers go to the agent verbatim, while
+   * everything that learns from the message sees only the user's words.
+   */
+  agentPayload?: unknown;
+  /** Lets this dispatch's middleware include an on-demand layer in its assembly (`RequestContext.requestLayer`). */
+  requestLayer?: (layerId: string) => void;
 }
 
 /**
@@ -355,6 +363,7 @@ export class Thread {
       stack: this._createStackView(),
       projectId: this.meta.projectId,
       messageId: opts?.messageId,
+      ...(opts?.requestLayer ? { requestLayer: opts.requestLayer } : {}),
     };
 
     const start = performance.now();
@@ -398,6 +407,8 @@ export class Thread {
             bridge: opts.nativeObservation.bridge,
             register: opts.nativeObservation.register,
             observe: opts.nativeObservation.observe,
+            interruptible: opts.nativeObservation.interruptible,
+            thought: opts.nativeObservation.thought,
             owner: Object.freeze({
               threadId: this.id,
               projectId: this.meta.projectId,
@@ -411,7 +422,11 @@ export class Thread {
 
     try {
       const result = await this.middleware.execute(ctx, () =>
-        agent.run(payload, filterOverride, meta),
+        agent.run(
+          opts?.agentPayload !== undefined ? (opts.agentPayload as TPayload) : payload,
+          filterOverride,
+          meta,
+        ),
       );
 
       const durationMs = performance.now() - start;
@@ -548,11 +563,11 @@ export class Thread {
     return {
       hasLayer: (id) => {
         const l = stack.getLayer(id);
-        return l ? l.isWarm : false;
+        return l ? l.assemblable : false;
       },
       getContent: (id) => {
         const l = stack.getLayer(id);
-        return l?.isWarm ? l.content : '';
+        return l?.assemblable ? l.content : '';
       },
       getState: (id) => stack.getLayer(id)?.state,
       get layerIds() {

package/src/types.ts

@@ -114,6 +114,12 @@ export interface CompletionOpts {
    * cached prefix; others ignore it. Messages are sent unchanged either way.
    */
   stablePrefix?: string;
+  /**
+   * The executor's context split into standing parts and per-turn text. A provider that keeps a
+   * native session delivers standing parts once and then only what changed (session-delivery.ts);
+   * others ignore it and send the messages unchanged.
+   */
+  delivery?: import('./session-delivery').SessionDelivery;
 }
 
 export interface CompletionResult {
@@ -125,6 +131,8 @@ export interface CompletionResult {
   /** Tool calls requested by the LLM (present when finishReason is "tool_use"). */
   readonly toolCalls?: ToolCall[];
   readonly raw?: unknown;
+  /** What a session provider delivered when it used `CompletionOpts.delivery`. */
+  readonly delivery?: import('./session-delivery').SessionDeliveryReport;
 }
 
 export interface EmbeddingResult {

package/src/permission-middleware.ts

@@ -1,80 +0,0 @@
-import { type Capability, CapabilityDeniedError, type CapabilityGate } from './capability';
-import type { DispatchContext, Middleware, MiddlewareNext } from './middleware';
-
-export interface PermissionCheckResult {
-  action: 'allow' | 'deny' | 'ask';
-  /** Optional modified payload (like Claude Code's updatedInput). */
-  modifiedPayload?: unknown;
-  /** Reason for denial. */
-  reason?: string;
-}
-
-export interface PermissionCheck {
-  /** Which capability this check relates to. */
-  capability: Capability;
-  /** Narrow the check to specific agents. If omitted, applies to all. */
-  agentIds?: string[];
-  /** Custom check logic beyond the gate. */
-  check: (ctx: DispatchContext) => PermissionCheckResult | Promise<PermissionCheckResult>;
-}
-
-export interface PermissionMiddlewareConfig {
-  /** The capability gate to check against. */
-  gate: CapabilityGate;
-  /** Thread ID for prompt context. */
-  threadId: string;
-  /** Default capability to check for all dispatches. Default: "llm:call". */
-  defaultCapability?: Capability;
-  /** Additional custom permission checks. */
-  checks?: PermissionCheck[];
-}
-
-/**
- * Creates a middleware that checks permissions before dispatch.
- *
- * Integrates the existing CapabilityGate into the dispatch pipeline.
- * Records permission decisions in ctx.annotations.
- */
-export function permissionMiddleware(config: PermissionMiddlewareConfig): Middleware {
-  const { gate, threadId, defaultCapability = 'llm:call', checks } = config;
-
-  return async (ctx: DispatchContext, next: MiddlewareNext) => {
-    // Check default capability via gate
-    const resolution = await gate.check(defaultCapability, {
-      agentId: ctx.agentId,
-      threadId,
-      detail: `Dispatch to agent ${ctx.agentId}`,
-    });
-
-    if (resolution.action === 'rejected') {
-      ctx.annotations['permission:denied'] = true;
-      ctx.annotations['permission:capability'] = defaultCapability;
-      throw new CapabilityDeniedError(defaultCapability, 'deny');
-    }
-
-    ctx.annotations['permission:approved'] = true;
-    ctx.annotations['permission:by'] = resolution.by;
-
-    // Run custom checks
-    if (checks) {
-      for (const check of checks) {
-        if (check.agentIds && !check.agentIds.includes(ctx.agentId)) continue;
-
-        const result = await check.check(ctx);
-
-        if (result.action === 'deny') {
-          ctx.annotations['permission:denied'] = true;
-          ctx.annotations['permission:capability'] = check.capability;
-          ctx.annotations['permission:reason'] = result.reason;
-          throw new CapabilityDeniedError(check.capability, 'deny');
-        }
-
-        if (result.modifiedPayload !== undefined) {
-          ctx.annotations['permission:modifiedPayload'] = result.modifiedPayload;
-        }
-      }
-    }
-
-    return next();
-  };
-}