@elevasis/sdk 1.42.0 → 1.44.0

package/dist/node/index.d.ts

@@ -274,113 +274,6 @@ interface IExecutionLogger {
     error(message: string, context?: LogContext): void;
 }
 
-/**
- * Model Configuration
- * Centralized model information, configuration, options, constraints, and validation
- * Single source of truth for all model-related definitions
- * Update manually when pricing changes or new models are added
- */
-
-/**
- * Supported Open AI models (direct SDK access)
- */
-type OpenAIModel = 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5.4-nano';
-/**
- * Supported OpenRouter models (explicit union for type safety)
- */
-type OpenRouterModel = 'openrouter/z-ai/glm-5';
-/**
- * Supported Google models (direct SDK access)
- */
-type GoogleModel = 'gemini-3-flash-preview' | 'gemini-3.1-flash-lite-preview';
-/**
- * Supported Anthropic models (direct SDK access via @anthropic-ai/sdk)
- */
-type AnthropicModel = 'claude-opus-5' | 'claude-sonnet-5' | 'claude-haiku-4-5-20251001' | 'claude-haiku-4-5';
-/** Supported LLM models */
-type LLMModel = OpenAIModel | OpenRouterModel | GoogleModel | AnthropicModel | 'mock';
-/**
- * GPT-5 model options schema
- */
-declare const GPT5OptionsSchema: z.ZodObject<{
-    reasoning_effort: z.ZodOptional<z.ZodEnum<{
-        minimal: "minimal";
-        low: "low";
-        medium: "medium";
-        high: "high";
-    }>>;
-    verbosity: z.ZodOptional<z.ZodEnum<{
-        low: "low";
-        medium: "medium";
-        high: "high";
-    }>>;
-}, z.core.$strip>;
-/**
- * OpenRouter model options schema
- * OpenRouter-specific options for routing and transforms
- */
-declare const OpenRouterOptionsSchema: z.ZodObject<{
-    transforms: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    route: z.ZodOptional<z.ZodEnum<{
-        fallback: "fallback";
-    }>>;
-}, z.core.$strip>;
-/**
- * Google model options schema
- * Gemini 3 specific options for thinking depth control
- */
-declare const GoogleOptionsSchema: z.ZodObject<{
-    thinkingLevel: z.ZodOptional<z.ZodEnum<{
-        minimal: "minimal";
-        low: "low";
-        medium: "medium";
-        high: "high";
-    }>>;
-}, z.core.$strip>;
-/**
- * Anthropic model options schema
- * Currently empty - future options must be added per supported model family
- */
-declare const AnthropicOptionsSchema: z.ZodObject<{}, z.core.$strict>;
-/**
- * Infer TypeScript types from schemas
- */
-type GPT5Options = z.infer<typeof GPT5OptionsSchema>;
-type MockOptions = Record<string, never>;
-type OpenRouterOptions = z.infer<typeof OpenRouterOptionsSchema>;
-type GoogleOptions = z.infer<typeof GoogleOptionsSchema>;
-type AnthropicOptions = z.infer<typeof AnthropicOptionsSchema>;
-type ModelSpecificOptions = GPT5Options | MockOptions | OpenRouterOptions | GoogleOptions | AnthropicOptions;
-/**
- * Model configuration for LLM execution
- * Belongs in resource definition (AgentDefinition, WorkflowDefinition, etc.)
- */
-interface ModelConfig {
-    model: LLMModel;
-    provider: 'openai' | 'anthropic' | 'openrouter' | 'google' | 'mock';
-    apiKey: string;
-    temperature?: number;
-    /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
-    maxOutputTokens?: number;
-    topP?: number;
-    /**
-     * Model-specific options (flat structure)
-     * Options are model-specific, not vendor-specific
-     * Available options defined in MODEL_INFO per model
-     * Validated at build time via validateModelOptions()
-     */
-    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";
@@ -743,165 +636,194 @@ type AgentResourceEntry = z.infer<typeof AgentResourceEntrySchema$1>;
 type ResourceEntry = z.infer<typeof ResourceEntrySchema>;
 
 /**
- * Shared form field types for dynamic form generation
- * Used by: Command Queue, Execution Runner UI, future form-based features
+ * Memory type definitions
+ * Types for agent memory management with semantic entry types
  */
 /**
- * Supported form field types for action payloads
- * Maps to Mantine form components
+ * Semantic memory entry types
+ * Use-case agnostic types that describe the purpose of each entry
+ * Memory types mirror action types for clarity and filtering
  */
-type FormFieldType = 'text' | 'textarea' | 'number' | 'select' | 'checkbox' | 'radio' | 'richtext';
+type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'error';
 /**
- * Form field definition
+ * 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`).
  */
-interface FormField {
-    /** Field key in payload object */
-    name: string;
-    /** Field label for UI */
-    label: string;
-    /** Field type (determines UI component) */
-    type: FormFieldType;
-    /** Default value */
-    defaultValue?: unknown;
-    /** Required field */
-    required?: boolean;
-    /** Placeholder text */
-    placeholder?: string;
-    /** Help text */
-    description?: string;
-    /** Options for select/radio */
-    options?: Array<{
-        label: string;
-        value: string | number;
-    }>;
-    /** Min/max for number */
-    min?: number;
-    max?: number;
-    /** Path to context value for pre-filling (dot notation, e.g., 'proposal.summary') */
-    defaultValueFromContext?: string;
-}
+type MemoryEntrySource = 'framework' | 'user' | 'tool' | 'model';
 /**
- * Form schema for action payload collection
+ * Memory entry - represents a single entry in agent memory
+ * Stored in agent memory, translated by adapters to vendor-specific formats
  */
-interface FormSchema {
-    /** Form title */
-    title?: string;
-    /** Form description */
-    description?: string;
-    /** Form fields */
-    fields: FormField[];
+interface MemoryEntry {
+    type: MemoryEntryType;
+    content: string;
+    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;
+    /**
+     * Which tool produced this entry. Set on `tool-result` entries so the model can tell N parallel
+     * results apart -- the framework instructs batching independent tool calls in one iteration, and
+     * an anonymous result is unattributable the moment two land in the same iteration. `addToolError`
+     * already carries this (folded into its `content` JSON); this is the same fact for the success
+     * path, carried as a real field instead of prose the caller has to parse back out.
+     */
+    toolName?: string;
+    /**
+     * Present when `truncateContent` cut this entry's `content` to fit its token budget. A sibling
+     * field, never text appended into `content` -- the notice used to be spliced into the string
+     * itself, which could (and did) land inside a JSON string literal `truncateContent` had just cut
+     * open, breaking `JSON.parse` on the far end. Absent means never truncated.
+     */
+    truncated?: {
+        omittedTokens: number;
+    };
+    /**
+     * Prompt-injection warning types found in `content`, screened once here -- when the entry is
+     * written -- instead of by re-scanning the whole accumulated envelope on every iteration it gets
+     * re-sent for (`screenRequest`'s `data-envelope` slot used to do exactly that). Empty array means
+     * screened and clean; `undefined` means never screened (entries that bypass `addToHistory`/`set`,
+     * or pre-existing snapshots from before this field existed).
+     */
+    warnings?: string[];
 }
-
 /**
- * Execution interface configuration
- * Defines how a resource is executed via the UI (forms, scheduling, webhooks)
- * Applies to both agents and workflows
+ * Agent memory - Self-orchestrated memory with session + working storage
+ * Agent has full control over what persists, framework handles auto-compaction
  */
-interface ExecutionInterface {
-    /** Form configuration for execution inputs */
-    form: ExecutionFormSchema;
-    /** Optional: Schedule configuration */
-    schedule?: ScheduleConfig;
-    /** Optional: Webhook trigger configuration */
-    webhook?: WebhookConfig;
+interface AgentMemory {
+    /**
+     * Session memory - Persists for session/conversation duration
+     * Never auto-trimmed by framework
+     * Agent-managed key-value store for critical information
+     * Agent provides strings, framework wraps in MemoryEntry
+     */
+    sessionMemory: Record<string, MemoryEntry>;
+    /**
+     * Working memory - Execution history
+     * Automatically compacted by framework when needed
+     * Agent doesn't control compaction
+     */
+    history: MemoryEntry[];
 }
 /**
- * Execution form schema
- * Extends FormSchema with execution-specific fields
+ * Memory status for agent awareness
  */
-interface ExecutionFormSchema extends FormSchema {
+interface MemoryStatus {
+    sessionMemoryKeys: number;
+    sessionMemoryLimit: number;
+    sessionMemoryTokens: number;
+    sessionMemoryTokenLimit: number;
     /**
-     * Field mappings to resource input schema
-     * Maps form field names to contract input paths
-     * If omitted, field names must match contract input keys exactly
+     * 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.
      */
-    fieldMappings?: Record<string, string>;
+    historyPercent: number;
     /**
-     * Submit button configuration
-     * Default: { label: 'Run', loadingLabel: 'Running...' }
+     * Tokens the history entries **in scope for the requested turn** occupy — the same set
+     * `toContextParts` puts in the envelope. Equal to `storedHistoryTokens` when `getStatus` is
+     * called without a turn.
+     *
+     * This is the number the model is shown, and it is scoped because the model is handed a scoped
+     * set. Counting the whole cross-turn array here meant the framing quoted the size of a store
+     * while the envelope beside it carried one turn's worth of it.
      */
-    submitButton?: {
-        label?: string;
-        loadingLabel?: string;
-        confirmMessage?: string;
-    };
+    historyTokens: number;
+    /**
+     * Tokens the **entire** history array occupies, across every turn the session snapshot restored.
+     *
+     * This is what compaction measures, because compaction trims that array. Scoping it to a turn
+     * would let the store grow without bound whenever the current turn happened to be small.
+     */
+    storedHistoryTokens: number;
+    /** `storedHistoryTokens` as a percentage of `historyBudget`. The auto-compaction trigger. */
+    storedHistoryPercent: number;
+    historyBudget: number;
 }
 /**
- * Schedule configuration for automated execution
+ * Memory constraints (optional limits)
  */
-interface ScheduleConfig {
-    /** Whether scheduling is enabled for this resource */
-    enabled: boolean;
-    /** Default schedule (cron expression) */
-    defaultSchedule?: string;
-    /** Allowed schedule patterns (if restricted) */
-    allowedPatterns?: string[];
+interface MemoryConstraints {
+    maxSessionMemoryKeys?: number;
+    maxMemoryTokens?: number;
 }
+
 /**
- * Webhook configuration for external triggers
+ * Types for the schema compiler. `compile.ts` walks a `JsonSchema` once, driven entirely by a
+ * `ProviderDialect`, and every server adapter compiles through it.
  */
-interface WebhookConfig {
-    /** Whether webhook trigger is enabled */
-    enabled: boolean;
-    /** Expected payload schema (for documentation) */
-    payloadSchema?: unknown;
-}
-
-interface WorkflowConfig extends ResourceDefinition {
-    type: 'workflow';
-    /** OM descriptor backing canonical identity and governance metadata. */
-    resource?: WorkflowResourceEntry;
-}
-interface WorkflowStepDefinition {
-    id: string;
-    name: string;
-    description: string;
-}
-type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>;
-interface LinearNext {
-    type: 'linear';
-    target: string;
-}
-interface ConditionalNext {
-    type: 'conditional';
-    routes: Array<{
-        condition: (data: unknown) => boolean;
-        target: string;
-    }>;
-    default: string;
-}
-type NextConfig = LinearNext | ConditionalNext | null;
-interface WorkflowStep extends WorkflowStepDefinition {
-    handler: StepHandler;
-    inputSchema: z.ZodSchema;
-    outputSchema: z.ZodSchema;
-    next: NextConfig;
-}
-interface WorkflowDefinition {
-    config: WorkflowConfig;
-    contract: Contract;
-    steps: Record<string, WorkflowStep>;
-    entryPoint: string;
-    /**
-     * Metrics configuration for ROI calculations
-     * Optional: Only needed if tracking automation savings
-     */
-    metricsConfig?: ResourceMetricsConfig;
+/**
+ * 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';
+/**
+ * A JSON Schema node, typed enough to be useful without pretending to validate the spec.
+ *
+ * The compiler has to accept schemas that arrive OUTSIDE the strict subset (that is the whole
+ * point of a dialect that can refuse or rewrite them) as well as the `$ref`/`$defs`/`const`/
+ * `$schema` shapes the strict subset has no vocabulary for at all. The index signature exists
+ * because tenant schemas carry keywords (`minLength`, `pattern`, `minimum`, ...) this compiler
+ * drops or refuses on, and they still need somewhere to type-check while they pass through
+ * `Object.entries`.
+ */
+interface JsonSchema {
+    type?: string | string[];
     /**
-     * Execution interface configuration (optional)
-     * If provided, workflow appears in Execution Runner UI
+     * The value is `JsonSchema | undefined`, not `JsonSchema`, because a property really can be
+     * declared with nothing describing it. `buildIterationResponseSchema` emits one per tool as
+     * `input: tool.inputSchema`, and `ToolDefinition.inputSchema` is typed `unknown` -- a tool
+     * deployed without one puts `undefined` under a key that exists.
+     *
+     * Both readers already handle it: `compileSchema` passes each value through `convertNode`, which
+     * takes `unknown`, and `collectErrors` opens with `if (!schema || typeof schema !== 'object')`
+     * above a comment naming this exact case. Declaring the value non-optional only hid that they
+     * were right to.
      */
-    interface?: ExecutionInterface;
+    properties?: Record<string, JsonSchema | undefined>;
+    items?: JsonSchema;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    minItems?: number;
+    maxItems?: number;
+    format?: string;
+    enum?: unknown[];
+    const?: unknown;
+    description?: string;
+    default?: unknown;
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    definitions?: Record<string, JsonSchema>;
+    $schema?: string;
+    $id?: string;
+    $anchor?: string;
     /**
-     * Lead-gen processing stage this workflow implements (optional).
-     * Must match a key in the platform lead-gen stage catalog.
-     * Used by org-os graph derivation to surface workflow→stage edges and
-     * by pipeline_config validation to confirm each catalog stage has an
-     * implementing workflow before a list is activated.
-     *
-     * Example: stageImplemented: 'verified' on the email-verification workflow.
+     * OpenAPI's nullability spelling, which is not JSON Schema's. It is declared because
+     * `response-schema-validator.ts` READS it (`schemaPermitsNull`) -- Google's schema dialect is
+     * OpenAPI-derived, so a schema that reaches the validator can carry it. No dialect in `compile.ts`
+     * writes or rewrites it; the canonical spelling this compiler emits is `type: ['x', 'null']`.
      */
-    stageImplemented?: string;
+    nullable?: boolean;
+    [key: string]: unknown;
 }
 
 /**
@@ -916,6 +838,31 @@ interface WorkflowDefinition {
 interface LLMMessage {
     role: 'system' | 'user' | 'assistant';
     content: string;
+    /**
+     * Marks this message as the end of a byte-stable prefix worth an Anthropic cache breakpoint,
+     * beyond the one the system prompt already gets. Anthropic's rule is "everything up to and
+     * including the marked block is cached", so this only ever needs to sit on ONE message -- the
+     * last one before content that changes.
+     *
+     * `buildAgentMessages` sets it on the last replayed prior-turn message: conversation history is
+     * fixed for the whole turn (only the framing/envelope after it grow per iteration), so it is the
+     * only part of a session agent's messages, besides the system prompt, that is ever byte-identical
+     * call to call. A hint rather than a mechanism deliberately -- an adapter that does not read it
+     * (OpenAI, OpenRouter, any test stub) just ignores the extra property; only the Anthropic adapter
+     * turns it into a wire `cache_control` block.
+     */
+    cacheBreakpoint?: boolean;
+    /**
+     * Prompt-injection warning types already found in this message's content, when the caller has
+     * already screened it and wants `screenRequest` to use that verdict instead of re-scanning.
+     *
+     * Set only on the data-envelope message by `buildAgentMessages`, sourced from
+     * `MemoryContextParts.envelopeWarnings` -- itself an aggregate of `MemoryEntry.warnings` stamped
+     * once per fragment when it entered memory. `undefined` means "not pre-screened"; `screenRequest`
+     * falls back to scanning the content directly, which is what every other message role/slot still
+     * does and what a hand-built message (tests, other callers) gets by default.
+     */
+    envelopeWarnings?: string[];
 }
 /**
  * Generic LLM generation request
@@ -923,16 +870,86 @@ interface LLMMessage {
  */
 interface LLMGenerateRequest {
     messages: LLMMessage[];
-    responseSchema: unknown;
+    /**
+     * JSON Schema for structured output. Omit it for an unstructured call.
+     *
+     * Absence is what turns validation off: `runGeneratePipeline` skips `validateResponseSchema`
+     * entirely when this is missing, whatever `validationSchema` holds.
+     *
+     * This was declared `responseSchema: unknown` -- required, and typed as nothing. `unknown` admits
+     * `undefined`, so "required" only ever forced the KEY to be written, and `createLLMCallTool`
+     * writes it as `undefined` on every call where the model supplies no usable schema. There was no
+     * type error available for that, and three separate layers re-derived the same nullability at
+     * runtime under three different rules -- truthiness in the pipeline, an object check in the
+     * validator, and a `'type'`-key check in the tool. Because the pipeline's was truthiness, `null`,
+     * `0` and `''` all quietly meant "no structured output" while the type insisted a schema was
+     * mandatory. Optional-and-typed is what those three were compensating for.
+     */
+    responseSchema?: JsonSchema;
     /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
     maxOutputTokens?: number;
     temperature?: number;
     topP?: number;
     signal?: AbortSignal;
+    /**
+     * Caller-supplied acceptance step (Wave D2b / decision A15). A pipeline-aware adapter
+     * (`UniversalLLMAdapter`, via `runGeneratePipeline`) runs this once per retry attempt, right
+     * after the response has passed `responseSchema` validation. Throw to reject the attempt --
+     * rejection is classified exactly like a thrown `LLMResponseParseError` from
+     * `validateResponseSchema`: retryable, no circuit-breaker verdict, and the attempt is recorded as
+     * a failure (`ai_calls` validation-failure row) rather than a clean success. Returning normally
+     * (including `undefined`) accepts the response.
+     *
+     * Optional, and a HINT rather than a dependency -- an adapter that does not read this field
+     * simply ignores it, so a caller must not assume it ran:
+     * - A bare test-stub `LLMAdapter` (many exist in this codebase) does not invoke it.
+     * - `PostMessageLLMAdapter` (`packages/sdk/src/worker/llm-adapter.ts`) cannot forward it at all --
+     *   functions cannot be structured-cloned across the worker `postMessage` boundary, so its
+     *   `params` object is built from an explicit allowlist that omits `accept`. The field is dropped
+     *   before `postMessage` is ever called (no `DataCloneError`), and the parent-side handler that
+     *   fulfils the call (`tool-dispatcher.ts`'s `case 'llm'`) rebuilds its own `LLMGenerateRequest`
+     *   from that allowlisted payload, so there is nothing to forward even in principle. This is the
+     *   path every deployed org-bundle agent and the `command-center-assistant` static module run
+     *   through today -- `accept` does not reach their retry loop.
+     *
+     * This is not a validation mechanism on its own: it does not decide whether output is acceptable,
+     * the caller's function does, by throwing or not. `callLLMForAgentIteration`
+     * (`execution/engine/agent/reasoning/adapters/agent-adapter-helpers.ts`) passes its Zod parse of
+     * the iteration response as this field, so a malformed-but-schema-valid iteration is re-sampled
+     * inside the retry loop instead of losing the turn -- for the in-process callers that can see it.
+     */
+    accept?: (output: unknown) => void;
+    /**
+     * The schema the RESPONSE is validated against, when that must differ from the schema the
+     * provider was asked to sample against. Defaults to `responseSchema` when omitted.
+     *
+     * **This does not affect what is sent to the provider.** `responseSchema` remains the only schema
+     * an adapter puts on the wire; this one is read solely by `runGeneratePipeline`'s validation step.
+     * Whether validation happens at all is still decided by `responseSchema` -- a request with no
+     * `responseSchema` is unstructured and stays unvalidated, whatever this field holds.
+     *
+     * A caller may legitimately ACCEPT A SUPERSET of what it ASKS FOR -- a document that validates a
+     * response more leniently than the one the provider was asked to sample against. No caller in this
+     * codebase supplies one today (agent iterations validate with a single Zod parse instead, see
+     * `agent-adapter-helpers.ts`), but the mechanism stays: `validateResponseSchema` does not descend
+     * into `anyOf`/`oneOf` regardless of which document is supplied here, so this field only ever
+     * changes which top-level/required/type keywords are checked, never which acceptance contract a
+     * union is read as.
+     *
+     * Unlike `accept` above, this is DATA. It is structured-cloneable, so it survives the worker
+     * `postMessage` boundary that drops `accept`: `PostMessageLLMAdapter` forwards it in its params
+     * allowlist and `tool-dispatcher.ts`'s `case 'llm'` puts it back on the `LLMGenerateRequest` it
+     * rebuilds parent-side. That is why a divergence expressible as a schema belongs here rather than
+     * in a callback -- deployed org-bundle agents run on the far side of that boundary.
+     */
+    validationSchema?: JsonSchema;
 }
 /**
  * Generic LLM generation response
- * Usage field is internal-only (stripped by UniversalLLMAdapter wrapper)
+ * `usage`, `cost`, `strictStatus` and `strictRefusalReasons` are observability fields. They are
+ * **read** by `UniversalLLMAdapter` and lifted onto the `ai_calls` row; they are **not removed**.
+ * The wrapper returns the base adapter's response object as-is, so a caller can observe all four.
+ * Earlier revisions of this file claimed they were stripped — they never were.
  */
 interface LLMGenerateResponse<T = unknown> {
     output: T;
@@ -940,35 +957,53 @@ interface LLMGenerateResponse<T = unknown> {
         inputTokens: number;
         outputTokens: number;
         totalTokens: number;
+        /**
+         * Anthropic-only: input tokens served from the prompt cache (`cache_read_input_tokens`), billed
+         * at 0.1x the base input rate. Optional so OpenAI/OpenRouter usage objects, which never report
+         * this, stay valid -- absent means "this provider doesn't report it," not "zero were read."
+         */
+        cacheReadInputTokens?: number;
+        /**
+         * Anthropic-only: input tokens written to the prompt cache this call
+         * (`cache_creation_input_tokens`), billed at 1.25x the base input rate. Same optionality
+         * rationale as `cacheReadInputTokens`.
+         */
+        cacheCreationInputTokens?: 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:
+     * What actually happened to `strict` on the request that produced this response.
      *
      * - `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
+     * - `refused` — `compileSchema` could not express the schema, so the request went out unstrict
+     * - `compileRejected` — the schema passed `compileSchema` 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)
+     * - `notAttempted` — the adapter did not send `strict` on this call
      *
      * 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.
+     * **Do not read this as "provider X never sends strict."** It describes one call, not an adapter.
+     * A previous revision of this comment enumerated OpenAI, Google and OpenRouter as adapters that
+     * never send `strict`, which was false for OpenRouter — it sends `strict: true` whenever the
+     * schema compiles, and separately reports `notAttempted`. That producer bug is still live; the
+     * fix is to make the value a return of schema compilation rather than a per-adapter literal.
+     * `MockAdapter` sets no value at all, so absence does not imply `notAttempted` either.
+     *
+     * Observability only — `UniversalLLMAdapter` lifts it onto the `ai_calls` row. It is not removed
+     * from the response.
      */
     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
+     * strings `compileSchema` 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.
+     * Observability only — `UniversalLLMAdapter` lifts it onto the `ai_calls` row. It is not removed
+     * from the response.
      */
     strictRefusalReasons?: string[];
 }
@@ -993,89 +1028,84 @@ interface LLMAdapter {
 }
 
 /**
- * Memory type definitions
- * Types for agent memory management with semantic entry types
+ * Model Configuration
+ * Centralized model information, configuration, options, constraints, and validation
+ * Single source of truth for all model-related definitions
+ * Update manually when pricing changes or new models are added
  */
+
 /**
- * Semantic memory entry types
- * Use-case agnostic types that describe the purpose of each entry
- * Memory types mirror action types for clarity and filtering
+ * Supported Open AI models (direct SDK access)
  */
-type MemoryEntryType = 'context' | 'input' | 'reasoning' | 'tool-result' | 'delegation-result' | 'error';
+type OpenAIModel = 'gpt-5' | 'gpt-5.4-mini' | 'gpt-5.4-nano';
 /**
- * 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`).
+ * Supported OpenRouter models (explicit union for type safety)
  */
-type MemoryEntrySource = 'framework' | 'user' | 'tool' | 'model';
+type OpenRouterModel = 'openrouter/z-ai/glm-5';
 /**
- * Memory entry - represents a single entry in agent memory
- * Stored in agent memory, translated by adapters to vendor-specific formats
+ * Supported Anthropic models (direct SDK access via @anthropic-ai/sdk)
  */
-interface MemoryEntry {
-    type: MemoryEntryType;
-    content: string;
-    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;
-}
+type AnthropicModel = 'claude-opus-5' | 'claude-sonnet-5' | 'claude-haiku-4-5-20251001' | 'claude-haiku-4-5';
+/** Supported LLM models */
+type LLMModel = OpenAIModel | OpenRouterModel | AnthropicModel | 'mock';
 /**
- * Agent memory - Self-orchestrated memory with session + working storage
- * Agent has full control over what persists, framework handles auto-compaction
+ * GPT-5 model options schema
  */
-interface AgentMemory {
-    /**
-     * Session memory - Persists for session/conversation duration
-     * Never auto-trimmed by framework
-     * Agent-managed key-value store for critical information
-     * Agent provides strings, framework wraps in MemoryEntry
-     */
-    sessionMemory: Record<string, MemoryEntry>;
-    /**
-     * Working memory - Execution history
-     * Automatically compacted by framework when needed
-     * Agent doesn't control compaction
-     */
-    history: MemoryEntry[];
-}
+declare const GPT5OptionsSchema: z.ZodObject<{
+    reasoning_effort: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+    verbosity: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
 /**
- * Memory status for agent awareness
+ * OpenRouter model options schema
+ * OpenRouter-specific options for routing and transforms
  */
-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;
-}
+declare const OpenRouterOptionsSchema: z.ZodObject<{
+    transforms: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    route: z.ZodOptional<z.ZodEnum<{
+        fallback: "fallback";
+    }>>;
+}, z.core.$strip>;
 /**
- * Memory constraints (optional limits)
+ * Anthropic model options schema
+ * Currently empty - future options must be added per supported model family
  */
-interface MemoryConstraints {
-    maxSessionMemoryKeys?: number;
-    maxMemoryTokens?: number;
+declare const AnthropicOptionsSchema: z.ZodObject<{}, z.core.$strict>;
+/**
+ * Infer TypeScript types from schemas
+ */
+type GPT5Options = z.infer<typeof GPT5OptionsSchema>;
+type MockOptions = Record<string, never>;
+type OpenRouterOptions = z.infer<typeof OpenRouterOptionsSchema>;
+type AnthropicOptions = z.infer<typeof AnthropicOptionsSchema>;
+type ModelSpecificOptions = GPT5Options | MockOptions | OpenRouterOptions | AnthropicOptions;
+/**
+ * Model configuration for LLM execution
+ * Belongs in resource definition (AgentDefinition, WorkflowDefinition, etc.)
+ */
+interface ModelConfig {
+    model: LLMModel;
+    provider: 'openai' | 'anthropic' | 'openrouter' | 'mock';
+    apiKey: string;
+    temperature?: number;
+    /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
+    maxOutputTokens?: number;
+    topP?: number;
+    /**
+     * Model-specific options (flat structure)
+     * Options are model-specific, not vendor-specific
+     * Available options defined in MODEL_INFO per model
+     * Validated at build time via validateModelOptions()
+     */
+    modelOptions?: ModelSpecificOptions;
 }
 
 /**
@@ -1095,8 +1125,27 @@ interface MemoryConstraints {
 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. */
+    /** Every stored fragment, JSON-encoded. Untrusted. */
     dataEnvelope: string;
+    /**
+     * Union of prompt-injection warning types already found across every fragment `dataEnvelope`
+     * actually carries this call, aggregated from verdicts stamped once when each fragment entered
+     * memory (see `MemoryEntry.warnings`) rather than by re-scanning `dataEnvelope`'s text on every
+     * iteration it gets rebuilt for. Elided fragments (see `ENVELOPE_FULL_RESULT_WINDOW`) contribute
+     * nothing here — their original content isn't what gets sent once they're stubbed.
+     *
+     * This is metadata about the envelope, not part of it: folding a detector's own finding into the
+     * model-visible JSON would hand a would-be attacker — plausibly the same person on the other end
+     * of a session conversation — direct feedback on which pattern tripped. A caller wiring this up
+     * (`screenRequest`'s `data-envelope` slot is the one that currently re-scans instead of reading
+     * this) should treat it exactly the way `screenRequest` already treats cross-turn history: it
+     * warns, but whether it blocks is that caller's decision to make, not this one's.
+     *
+     * Optional (not just possibly-empty): the fixture literals in `agent/reasoning/**` tests build
+     * `MemoryContextParts` by hand without it, and requiring it would make this signature's landing
+     * a forced edit across files this change does not otherwise touch.
+     */
+    envelopeWarnings?: string[];
 }
 /**
  * Memory Manager - Agent memory orchestration
@@ -1108,7 +1157,41 @@ declare class MemoryManager {
     private constraints;
     private logger?;
     private cachedSnapshot?;
+    /**
+     * Rolling correction for `estimateTokens`'s bias, learned from real provider usage.
+     * `undefined` until the first `recordActualUsage` call -- the cold-start state, where
+     * `estimate()` returns the raw `estimateTokens` output unscaled. See `recordActualUsage`.
+     */
+    private tokenCorrectionFactor?;
     constructor(memory: AgentMemory, constraints?: MemoryConstraints, logger?: AgentScopedLogger | undefined);
+    /**
+     * Record how far `estimateTokens` was from reality on a real provider call, and roll it into a
+     * correction applied to every estimate this instance makes from here on -- `getStatus`'s three
+     * token fields and `enforceSessionMemoryTokenLimit`'s eviction check, which is what
+     * `autoCompact`/`enforceHardLimits` actually decide compaction from (C3 / Wave M3).
+     *
+     * `estimateTokens` is `chars / 3.5` -- a constant-ratio guess with no knowledge of JSON escaping,
+     * key overhead, or real tokenizer behaviour. Every provider call already returns an EXACT count
+     * (`usage.inputTokens`) that reaches `ai_calls` and is then dropped; this is where it stops being
+     * dropped, without replacing the estimator outright -- a cold session still needs SOME number
+     * before its first real call completes, so the estimator stays the prior and this only corrects
+     * it once real data exists.
+     *
+     * `estimatedRequestTokens` must be `estimateTokens` applied to the SAME text `actualInputTokens`
+     * was billed for -- the whole assembled request (system prompt, tools, conversation history, the
+     * envelope, everything), not just what this class itself emits. `estimateTokens`'s bias is a
+     * property of the heuristic, not of which slice of the request it is pointed at, so measuring it
+     * against the full request (visible to the caller, not to this class) and applying the result to
+     * this class's own estimates (which can only ever see its own slice) is a fair trade -- one ratio,
+     * calibrated on real data, standing in for a per-segment breakdown nothing needs.
+     *
+     * Exponential moving average, not a straight replace: a single call's ratio is noisy, and a
+     * straight replace lets one outlier swing every compaction decision made afterward. Each new
+     * observation gets 30% weight, converging within a handful of calls without chasing one spike.
+     */
+    recordActualUsage(estimatedRequestTokens: number, actualInputTokens: number): void;
+    /** `estimateTokens`, scaled by the learned correction once one exists. See `recordActualUsage`. */
+    private estimate;
     /**
      * Set session memory entry (agent provides string, framework wraps it)
      * @param key - Session memory key
@@ -1150,6 +1233,14 @@ declare class MemoryManager {
      * 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".
+     *
+     * The running total is **recomputed** from the survivors rather than decremented per entry.
+     * `getStatus` estimates the pool as a ceiling of the joined sum, and a per-entry decrement is a
+     * sum of ceilings — the larger of the two by up to one token per key. The running total therefore
+     * fell faster than the pool did, and the loop could exit reporting a fit while the very next
+     * `getStatus` still read over the limit. Recomputing makes the loop's exit condition and the
+     * number it is judged by the same expression. The pool is capped at `MAX_SESSION_MEMORY_KEYS`
+     * entries, so the extra passes are bounded and cheap.
      */
     private enforceSessionMemoryTokenLimit;
     /**
@@ -1159,9 +1250,13 @@ declare class MemoryManager {
     getHistoryLength(): number;
     /**
      * Get memory status for agent awareness
+     *
+     * @param currentTurn - Turn to scope `historyTokens` / `historyPercent` to. Omit to measure the
+     *   whole store, which is what the compaction paths want. Callers building something the model
+     *   reads should pass it, so the count describes the set the model is actually handed.
      * @returns Memory status with token usage and key counts
      */
-    getStatus(): MemoryStatus;
+    getStatus(currentTurn?: number): MemoryStatus;
     /**
      * Create memory snapshot for persistence
      * Caches snapshot internally for later retrieval
@@ -1192,7 +1287,15 @@ declare class MemoryManager {
      * 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.
+     * History entries stay chronological. They used to be split into a "current iteration" slot
+     * (reverse chronological, for LLM positional bias) and an "earlier" slot -- but the LLM call
+     * always happens BEFORE `addToHistory` writes that iteration's own entries, so the
+     * current-iteration slot held nothing on any call that mattered. One chronological list replaces
+     * both.
+     *
+     * Tool results (and tool errors) older than `ENVELOPE_FULL_RESULT_WINDOW` iterations are carried
+     * as a short stub instead of their full content -- see `ENVELOPE_FULL_RESULT_WINDOW`. The STORE
+     * (`this.memory.history`) is untouched; only what this call carries is capped.
      *
      * @param currentIteration - Current iteration number (0 = pre-iteration)
      * @param currentTurn - Current turn number (optional, for session context filtering)
@@ -1201,175 +1304,145 @@ declare class MemoryManager {
 }
 
 /**
- * Knowledge Map Types
- *
- * Enables agents to navigate organizational knowledge through a lightweight
- * graph that lazy-loads capabilities on-demand.
- *
- * @module agent/knowledge-map
+ * Shared form field types for dynamic form generation
+ * Used by: Command Queue, Execution Runner UI, future form-based features
  */
-
 /**
- * Lightweight knowledge map (passed as agent property)
- *
- * Contains metadata about available knowledge nodes without loading
- * the full content upfront. Total size: ~300-500 tokens.
- *
- * Multi-tenancy is enforced via:
- * - File-scoped maps (organizations/{org-name}/knowledge/)
- * - ExecutionContext.organizationId passed to node.load()
+ * Supported form field types for action payloads
+ * Maps to Mantine form components
  */
-interface KnowledgeMap {
-    /** Available knowledge nodes indexed by ID */
-    nodes: Record<string, KnowledgeNode>;
-}
+type FormFieldType = 'text' | 'textarea' | 'number' | 'select' | 'checkbox' | 'radio' | 'richtext';
 /**
- * Single knowledge source
- *
- * Represents a domain knowledge area (CRM, brand guidelines, Excel tools)
- * that can be lazy-loaded to provide instructions and tools to agents.
+ * Form field definition
  */
-interface KnowledgeNode {
-    /** Unique identifier for this node (e.g., "crm", "brand-guidelines") */
-    id: string;
-    /**
-     * Description of when to use this knowledge
-     * Used for semantic matching against user intent
-     */
-    description: string;
-    /**
-     * Load knowledge content on-demand
-     *
-     * @param context - Execution context with organizationId for multi-tenancy
-     * @returns Promise resolving to knowledge content (prompt + optional tools)
-     */
-    load(context: ExecutionContext): Promise<KnowledgeContent>;
-    /**
-     * Loaded state flag
-     * Set to true after load() is called
-     */
-    loaded?: boolean;
-    /**
-     * Cached prompt (for system prompt serialization)
-     * Only the prompt is cached - tools go to toolRegistry, children flattened to nodes
-     */
-    prompt?: string;
+interface FormField {
+    /** Field key in payload object */
+    name: string;
+    /** Field label for UI */
+    label: string;
+    /** Field type (determines UI component) */
+    type: FormFieldType;
+    /** Default value */
+    defaultValue?: unknown;
+    /** Required field */
+    required?: boolean;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Help text */
+    description?: string;
+    /** Options for select/radio */
+    options?: Array<{
+        label: string;
+        value: string | number;
+    }>;
+    /** Min/max for number */
+    min?: number;
+    max?: number;
+    /** Path to context value for pre-filling (dot notation, e.g., 'proposal.summary') */
+    defaultValueFromContext?: string;
 }
 /**
- * Content returned by knowledge node
- *
- * Separates instructions (prompt) from capabilities (tools).
- * Tools are optional - some nodes only provide context.
- *
- * Supports recursive navigation - nodes can contain child nodes
- * that are discovered when the parent node is loaded.
+ * Form schema for action payload collection
  */
-interface KnowledgeContent {
-    /** Instructions and context (markdown format) */
-    prompt: string;
-    /** Tool implementations (optional) */
-    tools?: Tool[];
-    /**
-     * Child knowledge nodes (optional, recursive)
-     *
-     * Enables hierarchical navigation: base → specialized → deep expertise.
-     * Child nodes are flattened into the main knowledge map when parent loads,
-     * making them available for subsequent navigate-knowledge actions.
-     *
-     * Example: CRM base node returns crm-customers and crm-deals as children
-     */
-    nodes?: Record<string, KnowledgeNode>;
+interface FormSchema {
+    /** Form title */
+    title?: string;
+    /** Form description */
+    description?: string;
+    /** Form fields */
+    fields: FormField[];
 }
 
 /**
- * Agent-specific type definitions
- * Types for autonomous agents with tools, memory, and constraints
+ * Execution interface configuration
+ * Defines how a resource is executed via the UI (forms, scheduling, webhooks)
+ * Applies to both agents and workflows
  */
-
+interface ExecutionInterface {
+    /** Form configuration for execution inputs */
+    form: ExecutionFormSchema;
+    /** Optional: Schedule configuration */
+    schedule?: ScheduleConfig;
+    /** Optional: Webhook trigger configuration */
+    webhook?: WebhookConfig;
+}
 /**
- * Factory function for creating LLM adapters.
- * Injected into the Agent class to decouple the engine from server-only provider SDKs.
- * - API process: provides createLLMAdapter (real SDKs + process.env API keys)
- * - SDK worker: provides PostMessageLLMAdapter (proxies via platform.call)
- *
- * Uses `any` for optional params so both the real createLLMAdapter (with typed
- * AIUsageCollector/AICallContext) and the worker proxy (which ignores them) satisfy the type.
+ * Execution form schema
+ * Extends FormSchema with execution-specific fields
  */
-type LLMAdapterFactory = (config: ModelConfig, ...args: any[]) => LLMAdapter;
-type AgentKind = 'orchestrator' | 'specialist' | 'utility' | 'platform';
-interface AgentConfig extends ResourceDefinition {
-    type: 'agent';
-    /** OM descriptor backing canonical identity and governance metadata. */
-    resource?: AgentResourceEntry;
-    kind: AgentKind;
-    systemPrompt: string;
-    constraints?: AgentConstraints;
-    /**
-     * Session capability declaration (opt-in)
-     * If true, agent is designed for multi-turn session interactions
-     * Controls whether agent can use message action and appears in Sessions UI
-     *
-     * Use for:
-     * - Conversational agents with multi-turn interactions
-     * - Agents requiring persistent context across turns
-     * - Agents that need human-in-the-loop communication
-     */
-    sessionCapable?: boolean;
+interface ExecutionFormSchema extends FormSchema {
     /**
-     * Security level for system prompt hardening (auto-derived if omitted)
-     *
-     * - 'standard': Lightweight defense (3 rules) - default for non-session agents
-     * - 'hardened': Comprehensive defense (5 rules) - default for session-capable agents
-     * - 'none': No security prompt - for pure internal agents with no external input
-     *
-     * If omitted, derived from sessionCapable:
-     *   sessionCapable: true  -> 'hardened'
-     *   sessionCapable: false -> 'standard'
+     * Field mappings to resource input schema
+     * Maps form field names to contract input paths
+     * If omitted, field names must match contract input keys exactly
      */
-    securityLevel?: 'standard' | 'hardened' | 'none';
+    fieldMappings?: Record<string, string>;
     /**
-     * Memory management preferences (opt-in)
-     * If provided, agent can use memoryOps to manage session memory
-     * If omitted, agent has no memory management capabilities
-     *
-     * Agent-specific guidance on what to preserve, when to persist, and what to clean up.
-     * This guidance is injected into the system prompt when memory management is enabled.
-     *
-     * Use for:
-     * - Conversational agents needing cross-turn context
-     * - Agents managing complex user preferences
-     * - Agents tracking decisions over multiple iterations
+     * Submit button configuration
+     * Default: { label: 'Run', loadingLabel: 'Running...' }
      */
-    memoryPreferences?: string;
+    submitButton?: {
+        label?: string;
+        loadingLabel?: string;
+        confirmMessage?: string;
+    };
+}
+/**
+ * Schedule configuration for automated execution
+ */
+interface ScheduleConfig {
+    /** Whether scheduling is enabled for this resource */
+    enabled: boolean;
+    /** Default schedule (cron expression) */
+    defaultSchedule?: string;
+    /** Allowed schedule patterns (if restricted) */
+    allowedPatterns?: string[];
+}
+/**
+ * Webhook configuration for external triggers
+ */
+interface WebhookConfig {
+    /** Whether webhook trigger is enabled */
+    enabled: boolean;
+    /** Expected payload schema (for documentation) */
+    payloadSchema?: unknown;
+}
+
+interface WorkflowConfig extends ResourceDefinition {
+    type: 'workflow';
+    /** OM descriptor backing canonical identity and governance metadata. */
+    resource?: WorkflowResourceEntry;
 }
-interface AgentConstraints {
-    maxIterations?: number;
-    timeout?: number;
-    maxSessionMemoryKeys?: number;
-    maxMemoryTokens?: number;
+interface WorkflowStepDefinition {
+    id: string;
+    name: string;
+    description: string;
 }
-interface AgentDefinition {
-    config: AgentConfig;
+type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>;
+interface LinearNext {
+    type: 'linear';
+    target: string;
+}
+interface ConditionalNext {
+    type: 'conditional';
+    routes: Array<{
+        condition: (data: unknown) => boolean;
+        target: string;
+    }>;
+    default: string;
+}
+type NextConfig = LinearNext | ConditionalNext | null;
+interface WorkflowStep extends WorkflowStepDefinition {
+    handler: StepHandler;
+    inputSchema: z.ZodSchema;
+    outputSchema: z.ZodSchema;
+    next: NextConfig;
+}
+interface WorkflowDefinition {
+    config: WorkflowConfig;
     contract: Contract;
-    tools: Tool[];
-    /**
-     * Model configuration for LLM execution
-     * Specifies provider, API key, and model-specific options
-     */
-    modelConfig: ModelConfig;
-    /**
-     * Optional knowledge map for lazy-loading capabilities
-     * Enables agents to navigate organizational knowledge on-demand
-     */
-    knowledgeMap?: KnowledgeMap;
-    /**
-     * Preload memory before execution starts
-     * Handles BOTH context loading AND session restoration
-     *
-     * @param context - Execution context (includes sessionId if session turn)
-     * @returns Initial AgentMemory state (sessionMemory entries + optionally history)
-     */
-    preloadMemory?: (context: ExecutionContext) => Promise<AgentMemory> | AgentMemory;
+    steps: Record<string, WorkflowStep>;
+    entryPoint: string;
     /**
      * Metrics configuration for ROI calculations
      * Optional: Only needed if tracking automation savings
@@ -1377,31 +1450,19 @@ interface AgentDefinition {
     metricsConfig?: ResourceMetricsConfig;
     /**
      * Execution interface configuration (optional)
-     * If provided, agent appears in Execution Runner UI
+     * If provided, workflow appears in Execution Runner UI
      */
     interface?: ExecutionInterface;
-}
-/**
- * Agent execution context
- * Groups all state needed for agent execution phases
- */
-interface IterationContext {
-    config: AgentConfig;
-    contract: Contract;
-    toolRegistry: Map<string, Tool>;
-    memoryManager: MemoryManager;
-    executionContext: ExecutionContext;
-    iteration: number;
-    logger: AgentScopedLogger;
-    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.
+     * Lead-gen processing stage this workflow implements (optional).
+     * Must match a key in the platform lead-gen stage catalog.
+     * Used by org-os graph derivation to surface workflow→stage edges and
+     * by pipeline_config validation to confirm each catalog stage has an
+     * implementing workflow before a list is activated.
+     *
+     * Example: stageImplemented: 'verified' on the email-verification workflow.
      */
-    currentInput: string;
+    stageImplemented?: string;
 }
 
 declare const OntologyScopeSchema: z.ZodDefault<z.ZodObject<{
@@ -2681,6 +2742,32 @@ declare const OrganizationModelSchema$1: z.ZodObject<{
 
 type OrganizationModel$1 = z.infer<typeof OrganizationModelSchema$1>;
 
+/**
+ * AIUsageCollector
+ * Centralized token tracking that aggregates usage across all LLM calls in an execution
+ */
+declare class AIUsageCollector {
+    private model;
+    private calls;
+    private callSequence;
+    /**
+     * Record a single AI call with usage metrics
+     *
+     * @param usage - Token usage and latency data from LLM adapter
+     * @param callType - Type discriminator (agent-reasoning, tool, etc.)
+     * @param context - Optional typed context specific to callType
+     */
+    record(usage: LLMUsageData, callType?: BaseAICall['callType'], context?: AICallContext): void;
+    /**
+     * Get aggregated summary of all AI calls
+     */
+    getSummary(): AIUsageSummary;
+    /**
+     * Check if any usage has been recorded
+     */
+    hasUsage(): boolean;
+}
+
 /**
  * MetricsCollector
  * Tracks execution timing and ROI metrics
@@ -2731,6 +2818,17 @@ interface BaseAICall {
     costUsd: number;
     latencyMs: number;
     context?: AICallContext;
+    /**
+     * Anthropic-only: input tokens served from the prompt cache this call (`cache_read_input_tokens`),
+     * billed at 0.1x the base input rate. Already folded into `inputTokens`/`totalInputTokens` so
+     * aggregate totals reflect real usage -- present here as the raw breakdown, not additive on top.
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Anthropic-only: input tokens written to the prompt cache this call (`cache_creation_input_tokens`),
+     * billed at 1.25x the base input rate. Same folding rationale as `cacheReadInputTokens`.
+     */
+    cacheCreationInputTokens?: number;
     /**
      * 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
@@ -2796,6 +2894,41 @@ interface BaseAICall {
      * Existing readers that only look at the fields above are unaffected.
      */
     strictRefusalReasons?: string[];
+    /**
+     * Time spent in the base adapter's `generate()` call alone, excluding `responseSchema`
+     * validation. On a success or validation-failure row, `providerMs + validateMs === latencyMs`
+     * (modulo rounding) -- `latencyMs` keeps its existing meaning unchanged; this and `validateMs`
+     * are the same window split into its two components.
+     *
+     * Present on success and validation-failure rows. Absent on a blocked row (no provider call was
+     * made) and on rows written before this field existed.
+     */
+    providerMs?: number;
+    /**
+     * Time spent in `validateResponseSchema` alone. Omitted when the call carried no `responseSchema`
+     * (nothing to validate); `0` is a legitimate value meaning a schema was supplied and validation
+     * was effectively instant. See `providerMs` for how the two relate to `latencyMs`.
+     *
+     * Present on success and validation-failure rows that supplied a `responseSchema`. Absent on a
+     * blocked row and on rows written before this field existed.
+     */
+    validateMs?: number;
+    /**
+     * Total elapsed time for the WHOLE `generate()` call -- every retry attempt plus every backoff
+     * sleep between them. Unlike `latencyMs` (which is per-attempt and never includes backoff, by
+     * design -- see `runWithRetry`), this is the one number that answers "how long did the caller
+     * actually wait". On a call that never retried, `wallClockMs === latencyMs`. On a retried call,
+     * `wallClockMs` is strictly greater than any individual row's `latencyMs` from that same call, by
+     * at least the backoff time actually slept.
+     *
+     * The same value is attached to every row produced by one `generate()` call (a validation-failure
+     * row from an earlier attempt included), because it describes the call, not the attempt.
+     *
+     * Present on success and validation-failure rows. Absent on a blocked row -- a blocked call never
+     * reaches the retry loop, so `wallClockMs` would just restate `latencyMs` (0). Absent on rows
+     * written before this field existed.
+     */
+    wallClockMs?: number;
 }
 type AICallContext = AgentReasoningContext | AgentCompletionContext | WorkflowStepContext | ToolCallContext | OtherCallContext;
 interface AgentReasoningContext {
@@ -2841,6 +2974,16 @@ interface LLMUsageData {
     latencyMs: number;
     /** Actual cost from provider in USD (when available, e.g., OpenRouter) */
     cost?: number;
+    /**
+     * Anthropic-only: input tokens served from the prompt cache (`cache_read_input_tokens`), billed at
+     * 0.1x the base input rate. Absent for providers that never report it (OpenAI, OpenRouter).
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Anthropic-only: input tokens written to the prompt cache this call
+     * (`cache_creation_input_tokens`), billed at 1.25x the base input rate. Same absence rationale.
+     */
+    cacheCreationInputTokens?: number;
     /** Distinct prompt-injection pattern types detected in the request's user-role messages */
     inputWarnings?: string[];
     /** Additive per-source breakdown of `inputWarnings` — see `SourcedInputWarnings` */
@@ -2855,6 +2998,12 @@ interface LLMUsageData {
     strictStatus?: StrictStatus;
     /** Why the call went out unstrict, when a strict-capable adapter refused the schema */
     strictRefusalReasons?: string[];
+    /** Time in the base adapter's `generate()` alone, excluding `responseSchema` validation. See `BaseAICall.providerMs`. */
+    providerMs?: number;
+    /** Time in `validateResponseSchema` alone. Omitted when no `responseSchema` was supplied. See `BaseAICall.validateMs`. */
+    validateMs?: number;
+    /** Total elapsed for the whole `generate()` call, including every retry and every backoff sleep. See `BaseAICall.wallClockMs`. */
+    wallClockMs?: number;
 }
 interface AIUsageSummary {
     model: LLMModel;
@@ -2877,29 +3026,147 @@ interface ResourceMetricsConfig {
 }
 
 /**
- * AIUsageCollector
- * Centralized token tracking that aggregates usage across all LLM calls in an execution
+ * Agent-specific type definitions
+ * Types for autonomous agents with tools, memory, and constraints
  */
-declare class AIUsageCollector {
-    private model;
-    private calls;
-    private callSequence;
+
+/**
+ * Factory function for creating LLM adapters.
+ * Injected into the Agent class to decouple the engine from server-only provider SDKs.
+ * - API process: provides createLLMAdapter (real SDKs + process.env API keys)
+ * - SDK worker: provides PostMessageLLMAdapter (proxies via platform.call)
+ *
+ * Uses `any` for optional params so both the real createLLMAdapter (with typed
+ * AIUsageCollector/AICallContext) and the worker proxy (which ignores them) satisfy the type.
+ */
+type LLMAdapterFactory = (config: ModelConfig, ...args: any[]) => LLMAdapter;
+type AgentKind = 'orchestrator' | 'specialist' | 'utility' | 'platform';
+interface AgentConfig extends ResourceDefinition {
+    type: 'agent';
+    /** OM descriptor backing canonical identity and governance metadata. */
+    resource?: AgentResourceEntry;
+    kind: AgentKind;
+    systemPrompt: string;
+    constraints?: AgentConstraints;
     /**
-     * Record a single AI call with usage metrics
+     * Session capability declaration (opt-in)
+     * If true, agent is designed for multi-turn session interactions
+     * Controls whether agent can use message action and appears in Sessions UI
      *
-     * @param usage - Token usage and latency data from LLM adapter
-     * @param callType - Type discriminator (agent-reasoning, tool, etc.)
-     * @param context - Optional typed context specific to callType
+     * Use for:
+     * - Conversational agents with multi-turn interactions
+     * - Agents requiring persistent context across turns
+     * - Agents that need human-in-the-loop communication
      */
-    record(usage: LLMUsageData, callType?: BaseAICall['callType'], context?: AICallContext): void;
+    sessionCapable?: boolean;
     /**
-     * Get aggregated summary of all AI calls
+     * Overrides the default `message` requiredness for a session-capable agent (ignored for
+     * non-session agents, which always get `AgentCapabilities.message: 'off'`). Defaults to
+     * `'required'` -- see `AgentCapabilities.message`'s doc comment for why. Set `'optional'` only
+     * when the agent legitimately needs tool-only turns with no reply, and the deploy target can
+     * tolerate the blind-retry risk `validateResponseSchema` carries on any path where the schema is
+     * not compiled into a sampling grammar.
      */
-    getSummary(): AIUsageSummary;
+    messagePolicy?: 'optional' | 'required';
     /**
-     * Check if any usage has been recorded
+     * Explicit opt-in to skip the iteration loop and produce `contract.outputSchema`-shaped output in
+     * a single LLM call (round 3 decision B6: explicit opt-in, never inferred from `kind`,
+     * `sessionCapable`, or tool count -- so no existing agent changes shape by default). Structurally
+     * the normal path pays two calls minimum: `iterate()` always runs at least one, and `complete()`
+     * runs a second whose prompt re-derives the answer from history rather than reading what the
+     * iteration already decided. A single-shot classifier -- one input in, one structured output out,
+     * no multi-step reasoning needed -- does not need that second derivation; `complete()` already
+     * makes exactly the one call it needs, from `currentInput` directly.
+     *
+     * Requires `sessionCapable` to be falsy and `contract.outputSchema` to be present. `Agent`
+     * validates both during initialization and throws `AgentInitializationError` if either is missing,
+     * rather than silently falling back to the normal two-call path on a misconfigured opt-in. Tools
+     * registered on the agent are never invoked in this path -- there is no iteration loop to call
+     * them from, so an agent that needs tool calls before it can answer is not eligible regardless of
+     * this flag.
      */
-    hasUsage(): boolean;
+    singleShot?: boolean;
+    /**
+     * Security level for system prompt hardening (auto-derived if omitted)
+     *
+     * - 'standard': Lightweight defense (3 rules) - default for non-session agents
+     * - 'hardened': Comprehensive defense (5 rules) - default for session-capable agents
+     * - 'none': No security prompt - for pure internal agents with no external input
+     *
+     * If omitted, derived from sessionCapable:
+     *   sessionCapable: true  -> 'hardened'
+     *   sessionCapable: false -> 'standard'
+     */
+    securityLevel?: 'standard' | 'hardened' | 'none';
+    /**
+     * Memory management preferences (opt-in)
+     * If provided, agent can use memoryOps to manage session memory
+     * If omitted, agent has no memory management capabilities
+     *
+     * Agent-specific guidance on what to preserve, when to persist, and what to clean up.
+     * This guidance is injected into the system prompt when memory management is enabled.
+     *
+     * Use for:
+     * - Conversational agents needing cross-turn context
+     * - Agents managing complex user preferences
+     * - Agents tracking decisions over multiple iterations
+     */
+    memoryPreferences?: string;
+}
+interface AgentConstraints {
+    maxIterations?: number;
+    timeout?: number;
+    maxSessionMemoryKeys?: number;
+    maxMemoryTokens?: number;
+}
+interface AgentDefinition {
+    config: AgentConfig;
+    contract: Contract;
+    tools: Tool[];
+    /**
+     * Model configuration for LLM execution
+     * Specifies provider, API key, and model-specific options
+     */
+    modelConfig: ModelConfig;
+    /**
+     * Preload memory before execution starts
+     * Handles BOTH context loading AND session restoration
+     *
+     * @param context - Execution context (includes sessionId if session turn)
+     * @returns Initial AgentMemory state (sessionMemory entries + optionally history)
+     */
+    preloadMemory?: (context: ExecutionContext) => Promise<AgentMemory> | AgentMemory;
+    /**
+     * Metrics configuration for ROI calculations
+     * Optional: Only needed if tracking automation savings
+     */
+    metricsConfig?: ResourceMetricsConfig;
+    /**
+     * Execution interface configuration (optional)
+     * If provided, agent appears in Execution Runner UI
+     */
+    interface?: ExecutionInterface;
+}
+/**
+ * Agent execution context
+ * Groups all state needed for agent execution phases
+ */
+interface IterationContext {
+    config: AgentConfig;
+    contract: Contract;
+    toolRegistry: Map<string, Tool>;
+    memoryManager: MemoryManager;
+    executionContext: ExecutionContext;
+    iteration: number;
+    logger: AgentScopedLogger;
+    modelConfig: ModelConfig;
+    adapterFactory: LLMAdapterFactory;
+    /**
+     * 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;
 }
 
 /**
@@ -3047,6 +3314,19 @@ interface Tool {
     outputSchema: z.ZodSchema;
     execute: (options: ToolExecutionOptions) => Promise<unknown>;
     timeout?: number;
+    /**
+     * Optional per-tool output size bound, in approximate tokens. Today the ONLY size bound on tool
+     * output is a 4,000-token truncation applied post-hoc at memory insert -- after the payload is
+     * already fully materialized, validated against `outputSchema`, emitted as a session message, and
+     * logged. This field exists so a tool can declare its own bound up front instead.
+     *
+     * Enforcement is NOT here. `executor.ts:executeToolCall` is the single call site that produces the
+     * value handed to all four sinks (memory, the `agent:tool_result` event, the session message, and
+     * the log line) -- enforcing there, before that value is emitted, is what makes the four sinks agree
+     * instead of three of them seeing the untruncated payload. See that file's own comment for the
+     * exact insertion point.
+     */
+    maxOutputTokens?: number;
 }
 
 /**