@arnilo/prism 0.6.0 → 0.7.0

package/dist/context-budget.js

@@ -71,7 +71,7 @@ export function applyContextBudget(options) {
     const historyCursor = { index: 0 };
     // Measure once, then subtract each dropped item's own estimate (dropNext computes it
     // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
-    const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies, estimateTokens);
+    const kept = measureInputCost({ groups, context, skills, tools, skillContext, demotedBodies, estimateTokens });
     while (overBudget(kept, budget)) {
         const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies, historyCursor, estimateTokens);
         if (!drop) {
@@ -171,6 +171,15 @@ function omission(kind, id, message, estimateTokens) {
         byteLength: estimateMessageBytes(message),
     };
 }
+/**
+ * One O(n) cost measurement of the whole request (groups, context, skills, tool declarations).
+ * Shared with the attention-compiler gate, which measures once per turn and then subtracts a
+ * per-mutation delta instead of re-measuring — the same trick `applyContextBudget` uses.
+ */
+export function measureInputCost(options) {
+    return measureAll(options.groups, options.context ?? [], options.skills ?? [], options.tools, options.skillContext ?? {}, options.demotedBodies ?? EMPTY_DEMOTED_BODIES, options.estimateTokens ?? estimateTextTokens);
+}
+const EMPTY_DEMOTED_BODIES = new Set();
 /**
  * Resolves the budget's estimator, validating each return value: a host estimator that
  * yields NaN/negative/non-finite tokens would make every eviction decision unsound, so it

package/dist/contracts-core/agent.d.ts

@@ -33,6 +33,8 @@ export interface AgentDefinition {
     readonly metadata?: Readonly<Record<string, unknown>>;
     /** Optional escape hatch. When present, overrides declarative resolution. */
     create?(config?: AgentConfig): Promise<Agent> | Agent;
+    /** Opt-in attention compiler for the agent this definition resolves to (plan 074 C1). */
+    readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
 }
 /** Input to {@link resolveAgentDefinition}. All fields are optional; the host
  *  controls scope by which registries it passes. */
@@ -64,6 +66,9 @@ export interface AgentConfig {
     readonly toolsSearch?: import("../tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("../tool-result-fold.js").ToolResultFoldOptions;
+    /** Opt-in attention compiler (plan 074): `true` for defaults, an object to tune ratios/depth.
+     *  Omitted keeps today's request bytes; per-run options may only relax this setting. */
+    readonly attentionCompiler?: import("./attention.js").AttentionCompilerSetting;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -116,6 +121,8 @@ export interface SecureAgentOptions extends Omit<AgentConfig, "tools" | "validat
     readonly limits: RunLimits;
     readonly definitionRevision: string;
     readonly runState: Omit<AgentRunStateOptions, "definitionRevision" | "interruptBeforeTool">;
+    /** Optional host composition readiness assertions evaluated on creation. */
+    readonly composition?: import("../host-composition.js").HostCompositionOptions;
 }
 export interface Agent {
     readonly config: AgentConfig;

package/dist/contracts-core/attention.d.ts

@@ -0,0 +1,66 @@
+/** Attention Compiler contracts (plan 074 Tasks 2–5). Opt-in per-turn gate that measures the
+ *  assembled input and mutates a history clone only after a host ratio of the model input
+ *  cap. `resolveRunAttentionCompiler` turns the agent setting plus an optional run overlay
+ *  into the frozen handle the session hands to assembly; nothing declared here runs on its
+ *  own, and omitting the option keeps today's request bytes. */
+import type { CompactionTrigger } from "./compaction.js";
+import type { ModelConfig } from "./content.js";
+/** Input-cap resolution inputs shared by the compiler and `input_ratio` compaction triggers. */
+export interface AttentionInputCapOptions {
+    /** Host cap; when set it wins over `model.limits.contextWindow` (C2). */
+    readonly maxInputTokens?: number;
+    /** Output + next-turn headroom subtracted from the window (default 1024). */
+    readonly reserveTokens?: number;
+}
+export interface AttentionCompilerOptions extends AttentionInputCapOptions {
+    /** Fraction of `inputCap` that triggers mutation; in `(0, 1)` (default 0.75). */
+    readonly triggerRatio?: number;
+    /** Where compaction should fire relative to `triggerRatio`; must exceed it (default 0.9). */
+    readonly compactRatio?: number;
+    /** Newest thinking-bearing assistant turns kept intact (default 1). */
+    readonly thinkingKeepTurns?: number;
+    /** Newest tool results kept full (default 3). */
+    readonly keepLast?: number;
+    /** Tool names whose results are never stubbed, whatever the ratio. */
+    readonly excludeTools?: readonly string[];
+}
+/** Where the compiler is switched on: `true` uses the defaults, an object tunes them, `false`
+ *  (or omitted) leaves requests byte-for-byte as they are without the compiler. On
+ *  `RunOptions` the same shape is an overlay: `false` disables, `true` is a no-op, and an
+ *  object may only *relax* the agent setting (see `resolveRunAttentionCompiler`). */
+export type AttentionCompilerSetting = boolean | AttentionCompilerOptions;
+export interface AttentionCompilerContext {
+    /** Model limits used to resolve the input cap; ignored when `maxInputTokens` is set. */
+    readonly model?: Pick<ModelConfig, "limits">;
+    /** Validated at create so an unknown trigger type fails at config time, not on turn one. */
+    readonly compactionTrigger?: CompactionTrigger;
+}
+/** Validated, frozen configuration returned by `createAttentionCompiler`. */
+export interface AttentionCompiler {
+    readonly inputCap: number;
+    readonly reserveTokens: number;
+    readonly triggerRatio: number;
+    readonly compactRatio: number;
+    readonly thinkingKeepTurns: number;
+    readonly keepLast: number;
+    readonly excludeTools: readonly string[];
+}
+/** One mutated turn. Under-ratio turns emit nothing and produce no report (C14). */
+export interface AttentionReport {
+    /** Estimated tokens measured before this turn's mutation — the value compared to the ratio. */
+    readonly used: number;
+    /** Estimated tokens of the same request after this turn's mutation: the cost curve is `used` → `usedAfter`. */
+    readonly usedAfter: number;
+    readonly inputCap: number;
+    readonly triggerRatio: number;
+    /** Thinking turns absent from this request; rows re-applied from the sticky frontier count again. */
+    readonly droppedThinkingTurns: number;
+    /** Tool results stubbed in this request; rows re-applied from the sticky frontier count again. */
+    readonly stubbedToolResults: number;
+    /** Payload bytes the stubs took out of this request (never the stub text itself). */
+    readonly stubbedBytes: number;
+    /** True when the gate stopped with eligible rows left: the sticky frontier is partial. */
+    readonly truncated: boolean;
+    readonly runId?: string;
+    readonly sessionId?: string;
+}

package/dist/contracts-core/attention.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attention.js.map

package/dist/contracts-core/compaction.d.ts

@@ -21,15 +21,74 @@ export interface CompactionResult {
     readonly entries?: readonly SessionEntry[];
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Inputs a compaction trigger decides on. Estimates and ids only — never raw payloads. */
+export interface CompactionTriggerContext {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    readonly estimatedInputTokens: number;
+    readonly inputCapTokens: number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/** Host-programmable compact-when gate (plan 074 C11). Omitted → `thresholdEntries` only. */
+export type CompactionTrigger = {
+    readonly type: "threshold_entries";
+    readonly entries: number;
+} | {
+    readonly type: "input_ratio";
+    readonly ratio: number;
+} | {
+    readonly type: "custom";
+    readonly shouldCompact: (context: CompactionTriggerContext) => boolean | Promise<boolean>;
+};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export declare function assertCompactionTrigger(trigger: CompactionTrigger): CompactionTrigger;
 export interface CompactionOptions {
     readonly strategy?: CompactionStrategy;
     readonly thresholdEntries?: number;
+    /** Replaces the `thresholdEntries` gate when set; omitted keeps today's entry-count gate. */
+    readonly trigger?: CompactionTrigger;
     readonly keepRecentEntries?: number;
     readonly maxSummaryChars?: number;
     readonly secrets?: readonly (string | undefined)[];
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }
+/** Legacy gates a compaction decision can fall back to when no `trigger` is configured. */
+export interface ResolveShouldCompactOptions {
+    /** Host trigger; when set it replaces the legacy gates below. */
+    readonly trigger?: CompactionTrigger;
+    /** Session gate: compact when the branch holds more than this many entries. */
+    readonly thresholdEntries?: number;
+    /** Attach-loop gate: compact when the estimated input is at or above this many tokens. */
+    readonly compactAfterTokens?: number;
+}
+/** Everything a compaction decision reads. Estimates only — never raw payloads. */
+export interface ResolveShouldCompactInput {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    /** Estimated tokens of the would-be input; called at most once, and only when a ratio or custom trigger reads it. */
+    readonly estimateInputTokens: () => number;
+    /** Resolved input cap (the attention compiler's `resolveInputCap`); called at most once, and only when a ratio or custom trigger reads it. */
+    readonly resolveInputCapTokens: () => number;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+    /** Receives the failure behind a fail-closed `false`. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export declare function resolveShouldCompact(options: ResolveShouldCompactOptions, input: ResolveShouldCompactInput): Promise<boolean>;
 export interface CompactionMiddlewarePayload {
     readonly context: CompactionContext;
     readonly result: CompactionResult;

package/dist/contracts-core/compaction.js

@@ -1,2 +1,78 @@
-export {};
+/** Validate a host trigger at config time, so an unknown `type` fails at create (C11). */
+export function assertCompactionTrigger(trigger) {
+    if (typeof trigger !== "object" || trigger === null) {
+        throw new TypeError("compaction trigger must be an object");
+    }
+    switch (trigger.type) {
+        case "threshold_entries":
+            if (!Number.isSafeInteger(trigger.entries) || trigger.entries < 1) {
+                throw new TypeError("compaction trigger threshold_entries.entries must be a positive safe integer");
+            }
+            return trigger;
+        case "input_ratio":
+            if (!Number.isFinite(trigger.ratio) || trigger.ratio <= 0 || trigger.ratio >= 1) {
+                throw new TypeError("compaction trigger input_ratio.ratio must be a number in (0, 1)");
+            }
+            return trigger;
+        case "custom":
+            if (typeof trigger.shouldCompact !== "function") {
+                throw new TypeError("compaction trigger custom.shouldCompact must be a function");
+            }
+            return trigger;
+        default:
+            throw new TypeError(`unknown compaction trigger type: ${String(trigger.type)}`);
+    }
+}
+/**
+ * The single compact-when decision used by `autoCompact` and by host attach loops that gate their
+ * own post-run compaction (plan 074 C11).
+ *
+ * Precedence: an explicit `trigger` replaces the legacy gates. Only the token gates below a `trigger`
+ * replace are lazy — a `threshold_entries` trigger, or a `custom` callback that only reads counts,
+ * never pays for the token estimate or the input cap.
+ *
+ * Failure policy: a malformed trigger throws (`assertCompactionTrigger`, config error), while a
+ * throwing `custom.shouldCompact` — including a callback that reads an unresolvable cap — decides
+ * `false` and reports through `onError`, so a host bug can never compact on a guess.
+ */
+export async function resolveShouldCompact(options, input) {
+    let estimated;
+    let cap;
+    const estimateOnce = () => (estimated ??= input.estimateInputTokens());
+    const capOnce = () => (cap ??= input.resolveInputCapTokens());
+    const trigger = options.trigger;
+    if (trigger === undefined) {
+        if (options.thresholdEntries !== undefined)
+            return input.entryCount > options.thresholdEntries;
+        if (options.compactAfterTokens !== undefined)
+            return estimateOnce() >= options.compactAfterTokens;
+        return false;
+    }
+    assertCompactionTrigger(trigger);
+    if (trigger.type === "threshold_entries")
+        return input.entryCount > trigger.entries;
+    if (trigger.type === "input_ratio")
+        return estimateOnce() >= trigger.ratio * capOnce();
+    // Getter-backed so a callback that only reads counts never forces cap resolution, which throws
+    // when the active model declares no context window.
+    const context = {
+        sessionId: input.sessionId,
+        entryCount: input.entryCount,
+        get estimatedInputTokens() {
+            return estimateOnce();
+        },
+        get inputCapTokens() {
+            return capOnce();
+        },
+        ...(input.metadata === undefined ? {} : { metadata: input.metadata }),
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+    };
+    try {
+        return (await trigger.shouldCompact(context)) === true;
+    }
+    catch (error) {
+        input.onError?.(error);
+        return false;
+    }
+}
 //# sourceMappingURL=compaction.js.map

package/dist/contracts-core/provider.d.ts

@@ -83,6 +83,10 @@ export interface RealtimeSession {
     close(reason?: string, options?: {
         readonly signal?: AbortSignal;
     }): Promise<void>;
+    /** Return a host-dispatched tool result. Omitted on transports that cannot complete tools. */
+    completeTool?(callId: string, output: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
 }
 /** Factory a provider exposes for realtime sessions; not part of `AIProvider`. */
 export type RealtimeSessionFactory = (options: RealtimeSessionOptions) => RealtimeSession;

package/dist/contracts-core.d.ts

@@ -3,6 +3,7 @@
  * of `./contracts-core.js` is unchanged (0.1.4 barrel precedent). */
 export type { AudioContent, DocumentContent, FileContent } from "./content.js";
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/attention.js";
 export * from "./contracts-core/batch.js";
 export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";

package/dist/contracts-core.js

@@ -1,4 +1,5 @@
 export * from "./contracts-core/agent.js";
+export * from "./contracts-core/attention.js";
 export * from "./contracts-core/batch.js";
 export * from "./contracts-core/compaction.js";
 export * from "./contracts-core/content.js";

package/dist/contracts-protocol.d.ts

@@ -45,6 +45,9 @@ export type RealtimeEvent = {
 } | {
     readonly type: "tool_call";
     readonly call: ToolCallContent;
+} | {
+    readonly type: "usage";
+    readonly usage: Usage;
 } | {
     readonly type: "interrupted";
 } | {
@@ -97,11 +100,22 @@ export interface RunOptions {
     readonly activateAllSkills?: true;
     /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
     readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /**
+     * Optional per-run allow-list of registered tool names. Omitted → every registered tool (legacy).
+     * Empty → no tools this run. Unknown names fail closed. Cannot widen the agent registry or a
+     * checkpointed grant; resume intersects this list with current authority.
+     */
+    readonly toolNames?: readonly string[];
     /** Tools disclosure: "all" (default) sends every active tool schema; "search" sends top-k + the generated `search_tools` tool. */
     readonly toolsDisclosure?: import("./tool-search.js").ToolsDisclosure;
     readonly toolsSearch?: import("./tool-search.js").ToolsSearchOptions;
     /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
     readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
+    /** Per-run overlay for `AgentConfig.attentionCompiler` (plan 074 C12): `false` disables the
+     *  compiler for this run, `true` is a no-op, an object may only relax the agent setting
+     *  (gate ratios up, `keepLast`/`thinkingKeepTurns` down, `excludeTools` extended). Enabling
+     *  the compiler where the agent config left it off throws before the first provider turn. */
+    readonly attentionCompiler?: import("./contracts-core/attention.js").AttentionCompilerSetting;
     readonly instructionInjectors?: readonly InstructionInjector[];
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
@@ -299,6 +313,21 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId?: string;
     readonly summary: string;
+} | {
+    /** One attention-compiler mutation (plan 074 R15/T6): measured counts only, never message text. */
+    readonly type: "attention_compiled";
+    readonly sessionId: string;
+    readonly runId?: string;
+    readonly used: number;
+    /** Estimated tokens of the same request after this turn's mutation. */
+    readonly usedAfter: number;
+    readonly inputCap: number;
+    readonly triggerRatio: number;
+    readonly droppedThinkingTurns: number;
+    readonly stubbedToolResults: number;
+    /** Payload bytes the tool stubs took out of this request. */
+    readonly stubbedBytes: number;
+    readonly truncated: boolean;
 } | {
     readonly type: "retry_scheduled";
     readonly sessionId: string;

package/dist/contracts-run-state.d.ts

@@ -196,6 +196,12 @@ export interface AgentRunResumeOptions {
     readonly fencingToken?: number;
     /** Routes root decisions for nested-run approvals back to the child (e.g. supervisor). */
     readonly resumeNestedRun?: ResumeNestedRun;
+    /**
+     * Opt-in (plan 078 Task 7): receives the reconstructed session before the resumed run
+     * starts, so an observer (e.g. the supervisor's child-event pump) can subscribe while the
+     * run is still live. The session is valid only for the duration of this resume.
+     */
+    readonly onSession?: (session: AgentSession) => void;
     /** Opt-in (plan 015 Task 4): restore persisted loaded-skill names into the resumed session catalog. */
     readonly persistSessionState?: boolean;
     /** Opt-in (plan 018 Task 6): restore persisted loaded-skill bodies (requires `persistSessionState` too). */

package/dist/host-composition.d.ts

@@ -0,0 +1,78 @@
+import type { Agent, AgentConfig, CheckpointStore, SecureAgentOptions, SessionStore } from "./contracts.js";
+import type { SecretRedactor } from "./redaction.js";
+export type HostCompositionProfile = "personal" | "local-personal" | "business" | "business-worker" | "multi-tenant-worker";
+export declare class HostCompositionError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export interface HostCompositionGovernance {
+    readonly modelRouter?: unknown;
+    readonly budgetPolicy?: unknown;
+    readonly rateLimitPolicy?: unknown;
+    readonly supported?: boolean;
+    readonly [key: string]: unknown;
+}
+export interface HostCompositionOptions {
+    readonly profile?: HostCompositionProfile;
+    readonly agent?: Agent | AgentConfig | SecureAgentOptions | Partial<AgentConfig>;
+    readonly store?: SessionStore | CheckpointStore | {
+        readonly kind?: string;
+        readonly durable?: boolean;
+        [key: string]: unknown;
+    };
+    readonly checkpoints?: CheckpointStore;
+    readonly workspaceRoot?: string;
+    readonly sandboxRoots?: readonly string[];
+    readonly credentialRefs?: readonly string[];
+    readonly governance?: HostCompositionGovernance;
+    readonly redactor?: SecretRedactor;
+    /** Explicit opt-in for live network checks; inert by default. */
+    readonly liveChecks?: boolean;
+}
+export interface HostCompositionToolReport {
+    readonly name: string;
+    readonly description?: string;
+    readonly hasParameters: boolean;
+}
+export interface HostCompositionReport {
+    readonly profile: "personal" | "business";
+    readonly effectiveTools: readonly HostCompositionToolReport[];
+    readonly credentialReferences: readonly string[];
+    readonly ownership: {
+        readonly tenantId?: string;
+        readonly accountId?: string;
+        readonly userId?: string;
+    };
+    readonly storage: {
+        readonly kind: string;
+        readonly durable: boolean;
+    };
+    readonly sandbox: {
+        readonly workspaceRoot?: string;
+        readonly roots: readonly string[];
+        readonly isolated: boolean;
+    };
+    readonly governance: {
+        readonly permission: boolean;
+        readonly trust: boolean;
+        readonly redactor: boolean;
+        readonly validator: boolean;
+        readonly modelRouting: boolean;
+        readonly secure: boolean;
+    };
+    readonly readiness: {
+        readonly ok: boolean;
+        readonly errors: readonly string[];
+        readonly warnings: readonly string[];
+    };
+}
+/**
+ * Inspects a host composition in an inert, bounded, and secret-redacting manner.
+ * Performs zero network calls by default.
+ */
+export declare function inspectHostComposition(options: HostCompositionOptions): HostCompositionReport;
+/**
+ * Asserts that a host composition meets all readiness requirements for its profile.
+ * Throws HostCompositionError on failure.
+ */
+export declare function assertHostCompositionReadiness(options: HostCompositionOptions): HostCompositionReport;