@elevasis/sdk 1.40.0 → 1.41.1

package/dist/node/index.d.ts

@@ -372,6 +372,15 @@ interface ModelConfig {
     modelOptions?: ModelSpecificOptions;
 }
 
+/**
+ * What happened to `strict` on a request, recorded per call rather than inferred.
+ *
+ * `applied` and `notAttempted` are the two states that a refusal-only field cannot tell apart —
+ * both leave `strictRefusalReasons` empty. Recording the verdict positively is what makes "was
+ * this agent's output actually enforced?" answerable from an `ai_calls` row.
+ */
+type StrictStatus = 'applied' | 'refused' | 'compileRejected' | 'notAttempted';
+
 declare const ResourceGovernanceStatusSchema: z.ZodEnum<{
     active: "active";
     deprecated: "deprecated";
@@ -899,6 +908,7 @@ interface WorkflowDefinition {
  * Generic LLM Types
  * Universal interfaces for LLM interaction across all resource types
  */
+
 /**
  * Standard chat message format
  * Compatible with OpenAI, Anthropic, and other providers
@@ -932,6 +942,35 @@ interface LLMGenerateResponse<T = unknown> {
         totalTokens: number;
     };
     cost?: number;
+    /**
+     * What actually happened to `strict` on the request that produced this response. Every server
+     * adapter sets it on every call, so the value is a statement rather than an inference:
+     *
+     * - `applied` — the request carried `strict: true` and the grammar was in effect
+     * - `refused` — `toStrictSchema` could not express the schema, so the request went out unstrict
+     * - `compileRejected` — the schema passed `toStrictSchema` but the provider's grammar compiler
+     *   rejected it at request time, and the call was retried unstrict
+     * - `notAttempted` — this adapter does not send strict at all (OpenAI, Google, OpenRouter)
+     *
+     * This exists because `strictRefusalReasons` alone cannot answer the question. Its absence means
+     * "strict held" OR "nothing ever tried", and a prod run that recorded zero refusals while
+     * returning an array-typed field as a string is exactly the case where the difference matters.
+     *
+     * Internal-only, like `usage` — `UniversalLLMAdapter` lifts it onto the `ai_calls` row and
+     * strips it before the response reaches callers.
+     */
+    strictStatus?: StrictStatus;
+    /**
+     * Why this call went out WITHOUT `strict`, on an adapter that tried to send it with one.
+     *
+     * The detail behind a `refused` / `compileRejected` `strictStatus` — the short, stable reason
+     * strings `toStrictSchema` computes. Read `strictStatus` to answer "was it enforced"; read this
+     * to answer "why not".
+     *
+     * Internal-only, like `usage` — `UniversalLLMAdapter` lifts it onto the `ai_calls` row and
+     * strips it before the response reaches callers.
+     */
+    strictRefusalReasons?: string[];
 }
 /**
  * LLM Adapter interface
@@ -963,6 +1002,14 @@ interface LLMAdapter {
  * Memory types mirror action types for clarity and filtering
  */
 type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'delegation-result' | 'error';
+/**
+ * Who authored an entry's content.
+ *
+ * This is what lets the assembled prompt tell framework-authored text apart from text that
+ * originated outside the trust boundary. `'framework'` content is ours; the other three are not
+ * and are rendered inside the JSON data envelope (see `MemoryManager.toContextParts`).
+ */
+type MemoryEntrySource = 'framework' | 'user' | 'tool' | 'model';
 /**
  * Memory entry - represents a single entry in agent memory
  * Stored in agent memory, translated by adapters to vendor-specific formats
@@ -973,6 +1020,16 @@ interface MemoryEntry {
     timestamp: number;
     turnNumber: number | null;
     iterationNumber: number | null;
+    /**
+     * Provenance. **Optional on purpose** — `undefined` means unknown, which is what every
+     * pre-existing snapshot and every not-yet-redeployed tenant bundle produces. Read sites MUST
+     * test `== null`, never `=== undefined`: the `inTurnScope` predicate in `manager.ts` is the
+     * cautionary precedent, where a `=== undefined` check silently dropped every `null`-stamped
+     * entry. `isMemoryEntry` is deliberately NOT tightened to require this field; doing so would
+     * make every stored snapshot fail validation, and `restoreSessionMemory` fails open by
+     * starting the agent with empty memory rather than throwing.
+     */
+    source?: MemoryEntrySource;
 }
 /**
  * Agent memory - Self-orchestrated memory with session + working storage
@@ -1000,8 +1057,17 @@ interface MemoryStatus {
     sessionMemoryKeys: number;
     sessionMemoryLimit: number;
     currentKeys: string[];
+    sessionMemoryTokens: number;
+    sessionMemoryTokenLimit: number;
+    /**
+     * History tokens as a percentage of `historyBudget` — history ALONE, not history plus session
+     * memory. It previously reported the combined total under this name, so session memory growth
+     * read as history pressure and triggered history compaction that could not relieve it.
+     */
     historyPercent: number;
     historyTokens: number;
+    historyBudget: number;
+    totalTokens: number;
     tokenBudget: number;
 }
 /**
@@ -1018,6 +1084,20 @@ interface MemoryConstraints {
  * Agent provides strings, framework handles wrapping and auto-compaction
  */
 
+/**
+ * The framework's own framing message and the untrusted data envelope, as separate strings.
+ *
+ * They are separate because the model must be able to tell them apart, and so must the input
+ * sanitizer: the framing is framework-authored and trusted, the envelope is not. Concatenating
+ * them — which is what this replaced — made that distinction undecidable at the adapter and left
+ * the framework's own section headers inside the region scanned for delimiter injection.
+ */
+interface MemoryContextParts {
+    /** Framework-authored. Memory status and a description of the envelope. Carries NO stored content. */
+    framing: string;
+    /** Every stored fragment, JSON-encoded and source-tagged. Untrusted. */
+    dataEnvelope: string;
+}
 /**
  * Memory Manager - Agent memory orchestration
  * Provides ultra-simple API for agents (strings only)
@@ -1034,7 +1114,7 @@ declare class MemoryManager {
      * @param key - Session memory key
      * @param content - String content from agent
      */
-    set(key: string, content: string): void;
+    set(key: string, content: string, source?: MemoryEntrySource): void;
     /**
      * Get session memory entry content
      * @param key - Session memory key
@@ -1063,6 +1143,15 @@ declare class MemoryManager {
      * Emergency fallback if agent exceeds limits
      */
     enforceHardLimits(): void;
+    /**
+     * Evict oldest session memory entries until the pool fits its token limit.
+     *
+     * Key count and token count are different constraints: 25 short keys are fine, 25 large ones
+     * are not. Eviction is oldest-first by timestamp, matching the key-count path, and always
+     * leaves at least one entry so a single oversized key degrades to "one key" rather than to
+     * "memory silently emptied".
+     */
+    private enforceSessionMemoryTokenLimit;
     /**
      * Get history length (for logging and introspection)
      * @returns Number of entries in history
@@ -1086,14 +1175,29 @@ declare class MemoryManager {
      */
     getSnapshot(): AgentMemory | undefined;
     /**
-     * Build context string for LLM
-     * Serializes sessionmemory + history memory with clear sections
-     * Shows current iteration entries FIRST (reverse chronological) for LLM attention
+     * Build the framework framing and the untrusted data envelope for an LLM call.
+     *
+     * These are two separate strings because they are two different trust levels, and they used to
+     * be one. Concatenated, the framework's own `=== ... ===` section headers sat in the same string
+     * as stored tool output and user text, so the input sanitizer matched its own scaffolding on
+     * every call and nothing downstream could tell which half a match came from. Splitting them
+     * makes that distinction structural: the framing is ours, the envelope is not.
+     *
+     * The envelope is JSON, which additionally neutralizes the anchored-delimiter attack class —
+     * `JSON.stringify` escapes newlines, so a stored fragment cannot produce a line that starts
+     * with `===` no matter what it contains.
+     *
+     * The current turn's own input is deliberately NOT in either string. It travels as its own
+     * `role:'user'` message (see `buildAgentMessages`), which is the whole point: a model asked to
+     * treat "everything in this block" as data was also being handed the live question inside that
+     * block.
+     *
+     * Shows current iteration entries FIRST (reverse chronological) for LLM attention.
+     *
      * @param currentIteration - Current iteration number (0 = pre-iteration)
      * @param currentTurn - Current turn number (optional, for session context filtering)
-     * @returns Formatted memory context for LLM prompt
      */
-    toContext(currentIteration: number, currentTurn?: number): string;
+    toContextParts(currentIteration: number, currentTurn?: number): MemoryContextParts;
 }
 
 /**
@@ -1292,6 +1396,12 @@ interface IterationContext {
     modelConfig: ModelConfig;
     adapterFactory: LLMAdapterFactory;
     knowledgeMap?: KnowledgeMap;
+    /**
+     * The validated input for this execution, serialized. It travels here because the model gets
+     * it as its own `role:'user'` message; nothing else in this context carried it, so the input
+     * had to be read back out of memory history and shipped inside the memory block.
+     */
+    currentInput: string;
 }
 
 declare const OntologyScopeSchema: z.ZodDefault<z.ZodObject<{
@@ -2593,6 +2703,25 @@ declare class MetricsCollector {
     buildExecutionMetrics(metricsConfig?: ResourceMetricsConfig): ExecutionMetricsSummary;
 }
 
+/**
+ * Which `role:'user'` message slot a sanitizer warning came from, derived from the request's
+ * message array (no new plumbing from callers):
+ * - `'memory-context'` — the framework's framing message, identified by the `=== MEMORY STATUS ===`
+ *   banner. Framework-authored and trusted; it is no longer scanned at all, so this source should
+ *   not appear for agent calls. Retained because stale tenant bundles still emit the old combined
+ *   block, and their rows must stay readable.
+ * - `'data-envelope'` — the JSON envelope carrying every stored fragment. Untrusted, and the slot
+ *   where a match is genuine signal.
+ * - `'input'` — the turn's own input, on its own message. Also untrusted.
+ * - `'history'` — replayed prior turns. Untrusted, but already screened at their own front door,
+ *   so warnings here are recorded and never block (see `screenInput`).
+ */
+type InputWarningSource = 'memory-context' | 'data-envelope' | 'history' | 'input';
+/** Per-source breakdown of sanitizer warnings, so a memory-context echo is distinguishable from a genuine hit. */
+interface SourcedInputWarnings {
+    source: InputWarningSource;
+    warnings: string[];
+}
 interface BaseAICall {
     callSequence: number;
     callType: 'agent-reasoning' | 'agent-completion' | 'workflow-step' | 'tool' | 'other';
@@ -2602,6 +2731,71 @@ interface BaseAICall {
     costUsd: number;
     latencyMs: number;
     context?: AICallContext;
+    /**
+     * Distinct prompt-injection pattern types detected in the request's user-role messages.
+     * Present only when the input sanitizer matched something. Non-blocking matches ride along on
+     * the successful call's row; a blocked call records a row of its own (see `inputBlocked`).
+     *
+     * Flat union across all `role:'user'` messages — unchanged shape, kept for existing readers.
+     * See `inputWarningsBySource` for the per-slot breakdown.
+     */
+    inputWarnings?: string[];
+    /**
+     * Additive breakdown of `inputWarnings` by message slot (see `InputWarningSource`). Present only
+     * when at least one source produced a warning. Existing readers that only look at the flat
+     * `inputWarnings` array are unaffected.
+     */
+    inputWarningsBySource?: SourcedInputWarnings[];
+    /**
+     * True when the sanitizer blocked the request and no provider call was made.
+     * Such a row carries zero tokens, zero cost, and zero latency — it exists so a hard,
+     * user-visible failure is observable at all. Before this, a blocked call produced no row.
+     */
+    inputBlocked?: boolean;
+    /**
+     * The validator's message when the provider responded but its output failed `responseSchema`
+     * validation (e.g. `missing required field 'nextActions'`). Present only on such a row.
+     *
+     * This is NOT the blocked-input case: the provider DID respond and tokens WERE spent, so the row
+     * carries real `inputTokens`, `outputTokens`, cost and latency. It is a paid call that produced
+     * nothing usable, and before this it produced no row at all.
+     *
+     * One row per failed attempt — the adapter retries a validation failure up to `LLM_MAX_ATTEMPTS`,
+     * so a turn that exhausts its retries records three. Reading `inputTokens` across these rows is
+     * what measures malformed-output rate against context size rather than inferring it.
+     *
+     * Existing readers that only look at the fields above are unaffected.
+     */
+    outputValidationError?: string;
+    /**
+     * The raw model output that failed validation, JSON-stringified and truncated to a bounded
+     * length. Truncation is visible in the value itself (a trailing `…[truncated: N chars total]`),
+     * never silent. Present only alongside `outputValidationError`.
+     */
+    unvalidatedOutput?: string;
+    /**
+     * What happened to `strict` structured output on this call — `applied`, `refused`,
+     * `compileRejected`, or `notAttempted`. Every server adapter sets it, so this is the field that
+     * answers "is this agent's output actually being enforced?" without reading source.
+     *
+     * It replaces an inference that turned out to be unsound. `strictRefusalReasons` alone records
+     * only refusals, so an empty row meant "strict held" OR "this adapter never tries" — and a prod
+     * run recorded zero refusals while a call returned an array-typed field as a string, which a
+     * grammar makes impossible. The absence proved nothing, because the deployed API had no way to
+     * write the field at all.
+     *
+     * Absent on rows written before this field existed; that absence is itself diagnostic (the API
+     * predates the change). Existing readers that only look at the fields above are unaffected.
+     */
+    strictStatus?: StrictStatus;
+    /**
+     * Why this call went out without `strict`, when a strict-capable adapter refused the schema. The
+     * detail behind `strictStatus: 'refused' | 'compileRejected'` — read `strictStatus` for whether
+     * it was enforced, this for why not.
+     *
+     * Existing readers that only look at the fields above are unaffected.
+     */
+    strictRefusalReasons?: string[];
 }
 type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
 interface AgentReasoningContext {
@@ -2647,6 +2841,20 @@ interface LLMUsageData {
     latencyMs: number;
     /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
     cost?: number;
+    /** Distinct prompt-injection pattern types detected in the request's user-role messages */
+    inputWarnings?: string[];
+    /** Additive per-source breakdown of `inputWarnings` — see `SourcedInputWarnings` */
+    inputWarningsBySource?: SourcedInputWarnings[];
+    /** True when the sanitizer blocked the request and no provider call was made */
+    inputBlocked?: boolean;
+    /** Validator message when the provider responded but the output failed `responseSchema` validation */
+    outputValidationError?: string;
+    /** Raw model output that failed validation — JSON-stringified, truncated, truncation marked inline */
+    unvalidatedOutput?: string;
+    /** What happened to `strict` on this call — set by every server adapter, refusal or not */
+    strictStatus?: StrictStatus;
+    /** Why the call went out unstrict, when a strict-capable adapter refused the schema */
+    strictRefusalReasons?: string[];
 }
 interface AIUsageSummary {
     model: LLMModel;