@tangle-network/agent-app 0.43.56 → 0.43.58

package/dist/missions/index.d.ts

@@ -21,7 +21,9 @@ export { W as WithAgentActivity, s as stepAgentActivity } from '../agent-activit
  * silent clobber, never a stale overwrite.
  */
 type MissionStatus = 'scheduled' | 'running' | 'paused' | 'waiting_approval' | 'blocked' | 'succeeded' | 'failed' | 'aborted' | 'cancelled';
+/** Define possible statuses for a mission step during its execution lifecycle */
 type MissionStepStatus = 'pending' | 'running' | 'waiting_approval' | 'done' | 'failed';
+/** Define the structure and state details of a mission step within a workflow system */
 interface MissionStep {
     id: string;
     /** What the step should accomplish — an intent, never an implementation. */
@@ -39,6 +41,7 @@ interface MissionStep {
      *  full payload. */
     resultRef?: string;
 }
+/** Define the structure for tracking mission token usage, cost, duration, and LLM call counts */
 interface MissionCostLedger {
     tokensIn: number;
     tokensOut: number;
@@ -146,6 +149,7 @@ declare function isMissionTerminal(status: MissionStatus): boolean;
 /** The cooperative kill switch: a stop request rides metadata so it survives
  *  any status and is honored by the engine before the next side effect. */
 declare function isMissionStopRequested(mission: MissionRecord): boolean;
+/** Define input parameters for creating a mission including optional deterministic id and unique plan steps */
 interface CreateMissionInput {
     /** Explicit row id. Omit to use the service's id generator. Pass a
      *  DETERMINISTIC id (derived from the originating turn) when the caller may
@@ -175,6 +179,7 @@ interface CreateMissionInput {
      */
     extras?: Record<string, unknown>;
 }
+/** Define a patch to update the status and optional metadata of a step in a process */
 interface SetStepStatusPatch {
     sublabel?: string;
     resultRef?: string;
@@ -192,10 +197,12 @@ interface SetStepStatusPatch {
         ledgerDelta?: Partial<MissionCostLedger>;
     };
 }
+/** Define input parameters to complete a mission with status and optional summary */
 interface CompleteMissionInput {
     ok: boolean;
     summary?: string;
 }
+/** Define methods to create, retrieve, and update missions with controlled engine binding and metadata merging */
 interface MissionService {
     createMission(input: CreateMissionInput): Promise<MissionRecord>;
     getMission(id: string): Promise<MissionRecord | null>;
@@ -226,6 +233,7 @@ interface MissionService {
     markWaitingApproval(id: string, stepId: string): Promise<MissionOutcome<MissionRecord>>;
     complete(id: string, input: CompleteMissionInput): Promise<MissionOutcome<MissionRecord>>;
 }
+/** Define options for configuring mission service behavior including storage, time, and ID generation */
 interface MissionServiceOptions {
     store: MissionStorePort;
     /** Injectable clock (epoch ms). Default `Date.now`. */
@@ -240,7 +248,9 @@ interface MissionServiceOptions {
      */
     generateId?: () => string;
 }
+/** Create a mission service that manages mission records and audit events with customizable options */
 declare function createMissionService(options: MissionServiceOptions): MissionService;
+/** Define an in-memory mission store that tracks events and allows direct record writes */
 interface InMemoryMissionStore extends MissionStorePort {
     /** The full audit trail, append order. */
     events(): MissionAuditEvent[];
@@ -276,6 +286,7 @@ declare function createInMemoryMissionStore(): InMemoryMissionStore;
  *     The sink itself does no dedupe.
  */
 
+/** Handle mission stream events by processing emitted MissionStreamEvent objects */
 interface MissionEventSink {
     emit(event: MissionStreamEvent): void;
 }
@@ -294,7 +305,9 @@ interface MissionStreamStep {
     kind: string;
     status: MissionStreamStepStatus;
 }
+/** Define possible status values for a mission stream step */
 type MissionStreamStepStatus = 'pending' | 'running' | 'done' | 'failed' | 'waiting_approval';
+/** Define possible statuses representing the current state of a mission stream */
 type MissionStreamStatus = 'scheduled' | 'running' | 'paused' | 'waiting_approval' | 'succeeded' | 'aborted' | 'cancelled' | 'failed';
 /**
  * Discriminated union of every live mission event. Every member carries
@@ -483,11 +496,13 @@ declare function reduceMissionEvents(events: MissionStreamEvent[], seed?: Map<st
  * storage and only the resultRef is returned.
  */
 type SandboxDispatch = (input: SandboxDispatchInput) => Promise<SandboxDispatchResult>;
+/** Define input parameters for dispatching a mission step in the sandbox environment */
 interface SandboxDispatchInput {
     mission: MissionRecord;
     step: MissionStep;
     stepIndex: number;
 }
+/** Define the result of a completed sandbox dispatch including artifact reference and optional cost details */
 interface SandboxDispatchDoneResult {
     kind?: 'done';
     /** Small pointer at the produced artifact/output (vault path, asset id, exec
@@ -515,6 +530,7 @@ interface SandboxDispatchInProgressResult {
     pollAfterMs: number;
     sublabel?: string;
 }
+/** Resolve the result of a sandbox dispatch as done or in progress */
 type SandboxDispatchResult = SandboxDispatchDoneResult | SandboxDispatchInProgressResult;
 /** Outcome of running a single step. `cached` distinguishes a replay/skip
  *  (step was already done) from a fresh execution so the engine and its tests
@@ -560,6 +576,7 @@ type PlanOutcome = {
 } | {
     kind: 'not-found';
 };
+/** Define options to control mission plan execution with optional pre-step veto logic */
 interface MissionPlanRunOptions {
     /** Pre-step veto (kill switch, schedule window). A non-null return pauses the
      *  mission with that reason before the step's side effect starts. */
@@ -586,6 +603,7 @@ declare class RetryableStepError extends Error {
 /** Resolution states a gate proposal can be in. `approved`/`executed` unblock
  *  the gated step; everything else keeps the mission parked. */
 type MissionProposalResolution = 'pending' | 'approved' | 'rejected' | 'executed' | 'ignored';
+/** Define mission gate categories as step, budget, or volume */
 type MissionGateKind = 'step' | 'budget' | 'volume';
 /** Product classification of one step. Returned by
  *  {@link MissionGateOptions.classifyStep}; the matching rules (regexes, intent
@@ -635,6 +653,7 @@ interface MissionApprovalsPort {
      *  `externalAction: true` — the denominator of the volume cap. */
     countExternalActionProposals(missionId: string): Promise<number>;
 }
+/** Define configuration options for mission gating including approvals, step classification, and action limits */
 interface MissionGateOptions {
     approvals: MissionApprovalsPort;
     /** Which steps need human approval, and as what. Return null for an ungated
@@ -644,6 +663,7 @@ interface MissionGateOptions {
      *  required to request another. Default 5. */
     externalActionCap?: number;
 }
+/** Define configuration options for initializing and controlling the mission engine behavior */
 interface MissionEngineOptions {
     service: MissionService;
     /** Per-step USD estimate. Load-bearing twice: the budget gate parks on it
@@ -665,6 +685,7 @@ interface MissionEngineOptions {
      *  Default `['optional', 'best-effort']`. */
     nonFatalStepKinds?: readonly string[];
 }
+/** Resolve mission plan steps with concurrency control and durable state management */
 interface MissionEngine {
     /** Run exactly one plan step. Idempotent: re-invoking for a step already
      *  `done` returns the cached pointer without re-dispatching. A lost guarded
@@ -690,6 +711,7 @@ declare function stepGateProposalId(missionId: string, stepId: string): string;
 declare function budgetGateProposalId(missionId: string, stepId: string): string;
 /** Deterministic proposal id for an external-action volume-cap override. */
 declare function volumeGateProposalId(missionId: string, stepId: string): string;
+/** Create a mission engine configured with options to manage mission execution and error handling */
 declare function createMissionEngine(options: MissionEngineOptions): MissionEngine;
 
 /**
@@ -711,15 +733,18 @@ declare function createMissionEngine(options: MissionEngineOptions): MissionEngi
  *  non-fatal kind (a failure does not abort the mission); the rest are
  *  fatal-on-failure agent sub-tasks. */
 declare const DEFAULT_MISSION_STEP_KINDS: readonly string[];
+/** Define the structure representing a parsed mission step with id, kind, and intent fields */
 interface ParsedMissionStep {
     id: string;
     kind: string;
     intent: string;
 }
+/** Describe a mission with a title and an ordered list of parsed steps */
 interface ParsedMission {
     title: string;
     steps: ParsedMissionStep[];
 }
+/** Define options to specify allowed lowercase step kinds for parsing mission blocks */
 interface ParseMissionBlocksOptions {
     /** Allowed step kinds (lowercase). Default {@link DEFAULT_MISSION_STEP_KINDS}. */
     kinds?: readonly string[];

package/dist/missions/index.js

@@ -20,7 +20,7 @@ import {
   stepAgentActivity,
   stepGateProposalId,
   volumeGateProposalId
-} from "../chunk-YNALYIQ3.js";
+} from "../chunk-NLSSFLLS.js";
 export {
   DEFAULT_MISSION_STEP_KINDS,
   MISSION_CONTROL_CHANNEL_ID,

package/dist/{model-Bzi5i63l.d.ts → model-C8U0HZxL.d.ts}

@@ -70,6 +70,7 @@ interface IntakeGraph {
 }
 /** The reason an answer failed validation. */
 type AnswerRejectionReason = 'required' | 'wrong-type' | 'too-short' | 'too-long' | 'too-small' | 'too-large' | 'not-an-option' | 'invalid-url' | 'invalid-email' | 'unknown-question';
+/** Describe validation outcome of an answer including success status and optional rejection reason */
 interface AnswerValidationResult {
     ok: boolean;
     reason?: AnswerRejectionReason;

package/dist/{model-dF2h4xT9.d.ts → model-DmdkIteM.d.ts}

@@ -15,15 +15,20 @@ interface TangleModelConfig {
     apiKey: string;
     baseUrl: string;
 }
+/** Define the environment context for executing Tangle operations */
 type TangleExecutionEnvironment = 'development' | 'staging' | 'production' | 'test';
+/** Resolve the source of the Tangle execution key as either local environment or user input */
 type TangleExecutionKeySource = 'local-env' | 'user';
+/** Define error codes for Tangle execution key issues related to API key and account connection */
 type TangleExecutionKeyErrorCode = 'local_tangle_api_key_required' | 'tangle_account_not_connected';
+/** Resolve options for model configuration including environment variables and default router base URL */
 interface ResolveModelOptions {
     /** Env to read (defaults to process.env). */
     env?: Record<string, string | undefined>;
     /** Router base URL default when `TANGLE_ROUTER_BASE_URL` is unset. */
     defaultRouterBaseUrl?: string;
 }
+/** Resolve options for retrieving user API keys within a specific Tangle execution environment */
 interface ResolveUserTangleExecutionKeyOptions {
     /** Deployment context. Only local development may fall back to env keys. */
     environment?: TangleExecutionEnvironment;
@@ -32,16 +37,19 @@ interface ResolveUserTangleExecutionKeyOptions {
     /** App-owned lookup for the caller's linked platform API key. */
     getUserApiKey: () => string | null | undefined | Promise<string | null | undefined>;
 }
+/** Resolve options for retrieving a user's Tangle execution key with environment and API key access parameters */
 interface ResolveUserTangleExecutionKeyForUserOptions<UserId = string> {
     userId: UserId;
     environment?: TangleExecutionEnvironment;
     env?: Record<string, string | undefined>;
     getUserApiKey: (userId: UserId) => string | null | undefined | Promise<string | null | undefined>;
 }
+/** Define a resolved key combining an API key with its Tangle execution source */
 interface ResolvedTangleExecutionKey {
     apiKey: string;
     source: TangleExecutionKeySource;
 }
+/** Resolve options for retrieving a Tangle developer or user API key based on environment and context */
 interface ResolveTangleDevOrUserKeyOptions {
     /** Deployment context. Only local development may use the env key. */
     environment?: TangleExecutionEnvironment;
@@ -50,6 +58,7 @@ interface ResolveTangleDevOrUserKeyOptions {
     /** App-owned lookup for the caller's linked platform API key. */
     getUserApiKey: () => string | null | undefined | Promise<string | null | undefined>;
 }
+/** Represent HTTP error response containing status, error message, and specific error code */
 interface TangleExecutionKeyHttpError {
     status: number;
     body: {
@@ -57,11 +66,13 @@ interface TangleExecutionKeyHttpError {
         code: TangleExecutionKeyErrorCode;
     };
 }
+/** Define configuration options for creating a Tangle router model including API key and model details */
 interface CreateTangleRouterModelConfigOptions {
     apiKey: string;
     model: string;
     baseUrl?: string;
 }
+/** Define options for configuring billing enforcement environment variables and overrides */
 interface TangleBillingEnforcementOptions {
     /** Env to read (defaults to process.env). */
     env?: Record<string, string | undefined>;
@@ -71,15 +82,21 @@ interface TangleBillingEnforcementOptions {
      */
     enforcementEnvVar?: string;
 }
+/** Provide the default base URL for the Tangle router API endpoint */
 declare const DEFAULT_TANGLE_ROUTER_BASE_URL = "https://router.tangle.tools/v1";
+/** Define the default environment variable name for Tangle billing enforcement */
 declare const DEFAULT_TANGLE_BILLING_ENFORCEMENT_ENV_VAR = "TANGLE_BILLING_ENFORCEMENT";
+/** Resolve a string by trimming whitespace or returning null if empty or undefined */
 declare function trimOrNull(value: string | null | undefined): string | null;
+/** Represent execution key errors with specific codes and HTTP status information */
 declare class TangleExecutionKeyError extends Error {
     readonly code: TangleExecutionKeyErrorCode;
     readonly status: number;
     constructor(code: TangleExecutionKeyErrorCode, message: string, status: number);
 }
+/** Identify whether an error is a TangleExecutionKeyError based on its properties and type */
 declare function isTangleExecutionKeyError(error: unknown): error is TangleExecutionKeyError;
+/** Resolve the current Tangle execution environment based on provided or process environment variables */
 declare function resolveTangleExecutionEnvironment(env?: Record<string, string | undefined>): TangleExecutionEnvironment;
 /**
  * Shared policy for agent products that bill through the Tangle Platform.
@@ -91,6 +108,7 @@ declare function resolveTangleExecutionEnvironment(env?: Record<string, string |
  * `TANGLE_BILLING_ENFORCEMENT`.
  */
 declare function isTangleBillingEnforcementDisabled(opts?: TangleBillingEnforcementOptions): boolean;
+/** Resolve and format TangleExecutionKey HTTP errors into a standardized error object or return null */
 declare function tangleExecutionKeyHttpError(error: unknown): TangleExecutionKeyHttpError | null;
 /**
  * Shared dev-aware Tangle key resolution. Local development may use a server
@@ -107,6 +125,7 @@ declare function resolveTangleDevOrUserKey(opts: ResolveTangleDevOrUserKeyOption
  * model execution, billing, and account ownership aligned across products.
  */
 declare function resolveUserTangleExecutionKey(opts: ResolveUserTangleExecutionKeyOptions): Promise<ResolvedTangleExecutionKey>;
+/** Resolve the Tangle execution key for a specified user using provided environment and API key options */
 declare function resolveUserTangleExecutionKeyForUser<UserId = string>(opts: ResolveUserTangleExecutionKeyForUserOptions<UserId>): Promise<ResolvedTangleExecutionKey>;
 /**
  * Build an OpenAI-compatible Tangle Router model config from an already

package/dist/{model-BBwyOuWG.d.ts → model-DnfO_PdJ.d.ts}

@@ -12,7 +12,9 @@
  * conversion factor for bleed/trim-aware exports. Angles are degrees.
  * Nothing here touches Konva, React, or a database.
  */
+/** Define the current version number of the scene schema */
 declare const SCENE_SCHEMA_VERSION = 1;
+/** Define the structure and properties of a scene document including version, title, pages, settings, and metadata */
 interface SceneDocument {
     schemaVersion: typeof SCENE_SCHEMA_VERSION;
     title: string;
@@ -20,6 +22,7 @@ interface SceneDocument {
     settings: SceneSettings;
     metadata: Record<string, unknown>;
 }
+/** Define settings for scene export including print conversion factor for unit calculations */
 interface SceneSettings {
     /** Print conversion factor for mm↔px math at export; 96 = CSS default. */
     dpi: number;
@@ -37,6 +40,7 @@ interface PageGuides {
     vertical: number[];
     horizontal: number[];
 }
+/** Define the structure and properties of a scene page including layout, background, and elements */
 interface ScenePage {
     id: string;
     name: string;
@@ -64,6 +68,7 @@ interface SceneElementBase {
     visible: boolean;
     slot?: string;
 }
+/** Define a rectangular scene element with size, fill, optional stroke, and corner radius properties */
 interface RectElement extends SceneElementBase {
     kind: 'rect';
     width: number;
@@ -73,6 +78,7 @@ interface RectElement extends SceneElementBase {
     strokeWidth?: number;
     cornerRadius?: number;
 }
+/** Define properties for an ellipse element including dimensions, fill, and optional stroke details */
 interface EllipseElement extends SceneElementBase {
     kind: 'ellipse';
     width: number;
@@ -81,6 +87,7 @@ interface EllipseElement extends SceneElementBase {
     stroke?: string;
     strokeWidth?: number;
 }
+/** Define a line element with points, stroke, stroke width, and optional dash pattern */
 interface LineElement extends SceneElementBase {
     kind: 'line';
     /** Flat [x0, y0, x1, y1, ...] relative to (x, y); ≥ 2 points. */
@@ -89,6 +96,7 @@ interface LineElement extends SceneElementBase {
     strokeWidth: number;
     dash?: number[];
 }
+/** Define properties for a text element including content, style, alignment, and layout parameters */
 interface TextElement extends SceneElementBase {
     kind: 'text';
     text: string;
@@ -102,6 +110,7 @@ interface TextElement extends SceneElementBase {
     lineHeight: number;
     letterSpacing: number;
 }
+/** Define properties for an image element including source, dimensions, and fit mode */
 interface ImageElement extends SceneElementBase {
     kind: 'image';
     width: number;
@@ -121,13 +130,18 @@ interface VideoElement extends SceneElementBase {
     src: string;
     posterSrc?: string;
 }
+/** Define a group element that contains multiple child scene elements */
 interface GroupElement extends SceneElementBase {
     kind: 'group';
     children: SceneElement[];
 }
+/** Represent a graphical element in a scene including shapes, text, media, or groups */
 type SceneElement = RectElement | EllipseElement | LineElement | TextElement | ImageElement | VideoElement | GroupElement;
+/** Extract the kind property from a SceneElement to identify its element type */
 type SceneElementKind = SceneElement['kind'];
+/** Define all valid kinds of scene elements used in the application */
 declare const SCENE_ELEMENT_KINDS: readonly SceneElementKind[];
+/** Define rectangular boundaries with position and size properties */
 interface Bounds {
     x: number;
     y: number;
@@ -139,11 +153,14 @@ declare function elementExtent(element: SceneElement): {
     width: number;
     height: number;
 };
+/** Estimate the height of multiline text based on font size and line height */
 declare function estimateTextHeight(element: Pick<TextElement, 'text' | 'fontSize' | 'lineHeight'>): number;
 /** Axis-aligned bounding box in the parent's coordinate space, accounting for
  *  rotation about the element's top-left origin. */
 declare function elementAabb(element: SceneElement): Bounds;
+/** Determine if two rectangular bounds overlap or intersect each other */
 declare function boundsIntersect(a: Bounds, b: Bounds): boolean;
+/** Resolve and return a page by ID from a document or throw an error if not found */
 declare function requirePage(document: SceneDocument, pageId: string): ScenePage;
 /** Depth-first search across a page including group children. Returns the
  *  element and the array that owns it (page.elements or a group's children),
@@ -153,6 +170,7 @@ declare function findElement(page: ScenePage, elementId: string): {
     owner: SceneElement[];
     index: number;
 } | null;
+/** Resolve and return the element, its owner array, and index from the page by element ID */
 declare function requireElement(page: ScenePage, elementId: string): {
     element: SceneElement;
     owner: SceneElement[];
@@ -165,16 +183,22 @@ declare function collectSlots(document: SceneDocument): Map<string, {
     elementId: string;
     kind: SceneElementKind;
 }>;
+/** Define options to configure a new page including name, dimensions, and background color */
 interface NewPageOptions {
     name?: string;
     width?: number;
     height?: number;
     background?: string;
 }
+/** Create a new empty SceneDocument with a title and optional initial page settings */
 declare function createEmptyDocument(title: string, page?: NewPageOptions): SceneDocument;
+/** Create a new ScenePage with specified options and a unique identifier */
 declare function createPage(options: NewPageOptions, id: string): ScenePage;
+/** Assert that a value is a positive finite number and throw an error with a label if not */
 declare function assertPositiveFinite(value: number, label: string): void;
+/** Assert that a value is a finite number and throw an error with a label if not */
 declare function assertFinite(value: number, label: string): void;
+/** Validate that a string is a hex, rgb(a), or 'transparent' color and throw an error if not */
 declare function assertColor(value: string, label: string): void;
 /** Media boundary rule shared with sequences: remote http(s) or a rooted
  *  /api/ path — never sandbox-local files or data:/blob: blobs. Delegates to the
@@ -182,4 +206,4 @@ declare function assertColor(value: string, label: string): void;
  *  rule (trims, named-rejects local/inline schemes) so they cannot drift. */
 declare function assertSceneMediaSrc(value: string, label: string): void;
 
-export { type Bounds as B, type EllipseElement as E, type GroupElement as G, type ImageElement as I, type LineElement as L, type NewPageOptions as N, type PageBleed as P, type RectElement as R, SCENE_ELEMENT_KINDS as S, type TextElement as T, type VideoElement as V, type PageGuides as a, SCENE_SCHEMA_VERSION as b, type SceneDocument as c, type SceneElement as d, type SceneElementBase as e, type SceneElementKind as f, type ScenePage as g, type SceneSettings as h, assertColor as i, assertFinite as j, assertPositiveFinite as k, assertSceneMediaSrc as l, boundsIntersect as m, collectSlots as n, createEmptyDocument as o, createPage as p, elementAabb as q, elementExtent as r, estimateTextHeight as s, findElement as t, requireElement as u, requirePage as v };
+export { type Bounds as B, type EllipseElement as E, type GroupElement as G, type ImageElement as I, type LineElement as L, type NewPageOptions as N, type PageBleed as P, type RectElement as R, type ScenePage as S, type TextElement as T, type VideoElement as V, type SceneElement as a, type PageGuides as b, type SceneDocument as c, type SceneElementKind as d, SCENE_ELEMENT_KINDS as e, SCENE_SCHEMA_VERSION as f, type SceneElementBase as g, type SceneSettings as h, assertColor as i, assertFinite as j, assertPositiveFinite as k, assertSceneMediaSrc as l, boundsIntersect as m, collectSlots as n, createEmptyDocument as o, createPage as p, elementAabb as q, elementExtent as r, estimateTextHeight as s, findElement as t, requireElement as u, requirePage as v };

package/dist/model-resolution/index.d.ts

@@ -23,22 +23,28 @@ interface ModelInfo {
     _provider?: string;
     provider?: string;
 }
+/** Define possible origins for the chat model configuration values */
 type ChatModelSource = 'request' | 'workspace' | 'env' | 'default';
+/** Resolve a chat model with its identifier and source information */
 interface ResolvedChatModel {
     model: string;
     source: ChatModelSource;
 }
+/** Represent successful chat model validation with a true status and a validated string value */
 interface ChatModelValidationSuccess {
     succeeded: true;
     value: string;
 }
+/** Describe a failed chat model validation result with an error message */
 interface ChatModelValidationFailure {
     succeeded: false;
     error: string;
 }
+/** Resolve the outcome of validating a chat model as either success or failure */
 type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure;
 /** The catalog-fetch boundary: maps a router base URL to the raw model list. */
 type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>;
+/** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */
 interface ResolveChatModelInput {
     /** Per-request override (highest precedence). */
     requestModel?: string;
@@ -53,6 +59,7 @@ interface ResolveChatModelInput {
 /** Resolve the chat-turn model by the one canonical precedence. Blank values are
  *  treated as absent. */
 declare function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel;
+/** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */
 interface ValidateChatModelIdInput {
     /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */
     allowlist?: Iterable<string>;
@@ -71,8 +78,11 @@ interface ValidateChatModelIdInput {
  * rather than silently assigned a provider.
  */
 declare function validateChatModelId(modelId: unknown, input: ValidateChatModelIdInput): Promise<ChatModelValidationResult>;
+/** Resolve and return a trimmed string model ID or undefined for invalid or empty input */
 declare function cleanModelId(value: unknown): string | undefined;
+/** Validate if a model ID string conforms to length and character format requirements */
 declare function isWellFormedModelId(modelId: string): boolean;
+/** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */
 declare function catalogIdsForModel(model: ModelInfo): string[];
 
 export { type ChatModelSource, type ChatModelValidationFailure, type ChatModelValidationResult, type ChatModelValidationSuccess, type LoadModels, type ModelInfo, type ResolveChatModelInput, type ResolvedChatModel, type ValidateChatModelIdInput, catalogIdsForModel, cleanModelId, isWellFormedModelId, resolveChatModel, validateChatModelId };

package/dist/model-resolution/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Canonical chat-model resolution — identical across every agent app.\n *\n * The ONLY per-app inputs are DATA, never logic: the default model, the\n * allowlist, the env value the deployment set, and the catalog-fetch loader.\n * The logic is one precedence ladder + one fail-closed validator that every\n * product uses the same way — there is no per-product variant, no env-var name\n * baked in, and no backend dimension (router-vs-sandbox is the harness/dispatch\n * concern, not model resolution; a sandbox's provider default lives in the\n * sandbox subpath).\n *\n * - resolveChatModel: request > workspace > env > default. The product reads its\n *   own deploy env var and passes the VALUE as `envModel`; the shell knows no\n *   env-var names. Source is canonical: 'request' | 'workspace' | 'env' | 'default'.\n * - validateChatModelId: fail-closed. Admit an id that is in the allowlist, or\n *   equals the operator-set env model, or is served by the live router catalog\n *   (exact, or a bare id resolved to its canonical id when the suffix is unique).\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\nexport type ChatModelSource = 'request' | 'workspace' | 'env' | 'default'\n\nexport interface ResolvedChatModel {\n  model: string\n  source: ChatModelSource\n}\n\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\nexport interface ResolveChatModelInput {\n  /** Per-request override (highest precedence). */\n  requestModel?: string\n  /** Persisted workspace-pinned model. */\n  workspaceModel?: string\n  /** The value the deployment's model env var holds (the product reads its own\n   *  var name and passes the value — the shell stays env-var-name agnostic). */\n  envModel?: string\n  /** Final fallback (the product's default, typically profile.model.default). */\n  defaultModel: string\n}\n\n/** Resolve the chat-turn model by the one canonical precedence. Blank values are\n *  treated as absent. */\nexport function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel {\n  const request = cleanModelId(input.requestModel)\n  if (request) return { model: request, source: 'request' }\n  const workspace = cleanModelId(input.workspaceModel)\n  if (workspace) return { model: workspace, source: 'workspace' }\n  const env = cleanModelId(input.envModel)\n  if (env) return { model: env, source: 'env' }\n  return { model: input.defaultModel, source: 'default' }\n}\n\nexport interface ValidateChatModelIdInput {\n  /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */\n  allowlist?: Iterable<string>\n  /** The operator-set env model value — always admitted (operator-trusted). */\n  envModel?: string\n  /** Catalog loader; required to reach the catalog path. */\n  loadModels?: LoadModels\n  /** Catalog endpoint base; required to reach the catalog path. */\n  routerBaseUrl?: string\n}\n\n/**\n * Fail-closed model-id validation. Accepts an id only when it is well-formed AND\n * (in the allowlist, or equals the operator-set env model, or served by the live\n * catalog). A bare id (no provider prefix) resolves to its canonical id only when\n * the suffix is unique across the catalog — an ambiguous suffix is rejected\n * rather than silently assigned a provider.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  input: ValidateChatModelIdInput,\n): Promise<ChatModelValidationResult> {\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n\n  const allowed = new Set(input.allowlist ?? [])\n  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  // The operator-set env model is trusted without a catalog round-trip.\n  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned }\n\n  if (!input.loadModels || typeof input.routerBaseUrl !== 'string' || input.routerBaseUrl.length === 0) {\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await input.loadModels(input.routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (ids.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  if (!cleaned.includes('/')) {\n    const canonicalBySuffix = new Map<string, string[]>()\n    for (const model of catalog) {\n      if (typeof model.id !== 'string' || !model.id.trim()) continue\n      const canonical = canonicalModelId(model)\n      if (!canonical.includes('/')) continue\n      const suffix = canonical.split('/').slice(1).join('/')\n      const entries = canonicalBySuffix.get(suffix)\n      if (entries) entries.push(canonical)\n      else canonicalBySuffix.set(suffix, [canonical])\n    }\n    const matches = canonicalBySuffix.get(cleaned)\n    if (matches && matches.length === 1) return { succeeded: true, value: matches[0]! }\n  }\n\n  return { succeeded: false, error: `Model is not available: ${cleaned}` }\n}\n\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n  return [...ids]\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/model-resolution/index.ts"],"sourcesContent":["/**\n * Canonical chat-model resolution — identical across every agent app.\n *\n * The ONLY per-app inputs are DATA, never logic: the default model, the\n * allowlist, the env value the deployment set, and the catalog-fetch loader.\n * The logic is one precedence ladder + one fail-closed validator that every\n * product uses the same way — there is no per-product variant, no env-var name\n * baked in, and no backend dimension (router-vs-sandbox is the harness/dispatch\n * concern, not model resolution; a sandbox's provider default lives in the\n * sandbox subpath).\n *\n * - resolveChatModel: request > workspace > env > default. The product reads its\n *   own deploy env var and passes the VALUE as `envModel`; the shell knows no\n *   env-var names. Source is canonical: 'request' | 'workspace' | 'env' | 'default'.\n * - validateChatModelId: fail-closed. Admit an id that is in the allowlist, or\n *   equals the operator-set env model, or is served by the live router catalog\n *   (exact, or a bare id resolved to its canonical id when the suffix is unique).\n */\n\n/** The router /v1/models entry shape this module reads. Minimal on purpose. */\nexport interface ModelInfo {\n  id: string\n  name?: string\n  _provider?: string\n  provider?: string\n}\n\n/** Canonical (provider-prefixed) id for a catalog entry: pass through an id that\n *  already carries a provider, else prefix the entry's provider when present. */\nfunction canonicalModelId(model: ModelInfo): string {\n  if (model.id.includes('/')) return model.id\n  const provider = model._provider ?? model.provider\n  return provider ? `${provider}/${model.id}` : model.id\n}\n\n/** Define possible origins for the chat model configuration values */\nexport type ChatModelSource = 'request' | 'workspace' | 'env' | 'default'\n\n/** Resolve a chat model with its identifier and source information */\nexport interface ResolvedChatModel {\n  model: string\n  source: ChatModelSource\n}\n\n/** Represent successful chat model validation with a true status and a validated string value */\nexport interface ChatModelValidationSuccess {\n  succeeded: true\n  value: string\n}\n\n/** Describe a failed chat model validation result with an error message */\nexport interface ChatModelValidationFailure {\n  succeeded: false\n  error: string\n}\n\n/** Resolve the outcome of validating a chat model as either success or failure */\nexport type ChatModelValidationResult = ChatModelValidationSuccess | ChatModelValidationFailure\n\n/** The catalog-fetch boundary: maps a router base URL to the raw model list. */\nexport type LoadModels = (routerBaseUrl: string) => Promise<ModelInfo[]>\n\n/** Resolve the effective chat model input by prioritizing request, workspace, environment, and default models */\nexport interface ResolveChatModelInput {\n  /** Per-request override (highest precedence). */\n  requestModel?: string\n  /** Persisted workspace-pinned model. */\n  workspaceModel?: string\n  /** The value the deployment's model env var holds (the product reads its own\n   *  var name and passes the value — the shell stays env-var-name agnostic). */\n  envModel?: string\n  /** Final fallback (the product's default, typically profile.model.default). */\n  defaultModel: string\n}\n\n/** Resolve the chat-turn model by the one canonical precedence. Blank values are\n *  treated as absent. */\nexport function resolveChatModel(input: ResolveChatModelInput): ResolvedChatModel {\n  const request = cleanModelId(input.requestModel)\n  if (request) return { model: request, source: 'request' }\n  const workspace = cleanModelId(input.workspaceModel)\n  if (workspace) return { model: workspace, source: 'workspace' }\n  const env = cleanModelId(input.envModel)\n  if (env) return { model: env, source: 'env' }\n  return { model: input.defaultModel, source: 'default' }\n}\n\n/** Define input parameters for validating chat model IDs with optional allowlist and catalog access details */\nexport interface ValidateChatModelIdInput {\n  /** Ids accepted without a catalog round-trip (defaults + operator-trusted). */\n  allowlist?: Iterable<string>\n  /** The operator-set env model value — always admitted (operator-trusted). */\n  envModel?: string\n  /** Catalog loader; required to reach the catalog path. */\n  loadModels?: LoadModels\n  /** Catalog endpoint base; required to reach the catalog path. */\n  routerBaseUrl?: string\n}\n\n/**\n * Fail-closed model-id validation. Accepts an id only when it is well-formed AND\n * (in the allowlist, or equals the operator-set env model, or served by the live\n * catalog). A bare id (no provider prefix) resolves to its canonical id only when\n * the suffix is unique across the catalog — an ambiguous suffix is rejected\n * rather than silently assigned a provider.\n */\nexport async function validateChatModelId(\n  modelId: unknown,\n  input: ValidateChatModelIdInput,\n): Promise<ChatModelValidationResult> {\n  const cleaned = cleanModelId(modelId)\n  if (!cleaned) return { succeeded: false, error: 'Model id must be a non-empty string.' }\n  if (!isWellFormedModelId(cleaned)) return { succeeded: false, error: `Model id is malformed: ${cleaned}` }\n\n  const allowed = new Set(input.allowlist ?? [])\n  if (allowed.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  // The operator-set env model is trusted without a catalog round-trip.\n  if (cleanModelId(input.envModel) === cleaned) return { succeeded: true, value: cleaned }\n\n  if (!input.loadModels || typeof input.routerBaseUrl !== 'string' || input.routerBaseUrl.length === 0) {\n    return { succeeded: false, error: `Model is not available: ${cleaned}` }\n  }\n\n  let catalog: ModelInfo[]\n  try {\n    catalog = await input.loadModels(input.routerBaseUrl)\n  } catch (err) {\n    const message = err instanceof Error ? err.message : String(err)\n    return { succeeded: false, error: `Could not validate model catalog: ${message}` }\n  }\n\n  const ids = new Set(catalog.flatMap(catalogIdsForModel))\n  if (ids.has(cleaned)) return { succeeded: true, value: cleaned }\n\n  if (!cleaned.includes('/')) {\n    const canonicalBySuffix = new Map<string, string[]>()\n    for (const model of catalog) {\n      if (typeof model.id !== 'string' || !model.id.trim()) continue\n      const canonical = canonicalModelId(model)\n      if (!canonical.includes('/')) continue\n      const suffix = canonical.split('/').slice(1).join('/')\n      const entries = canonicalBySuffix.get(suffix)\n      if (entries) entries.push(canonical)\n      else canonicalBySuffix.set(suffix, [canonical])\n    }\n    const matches = canonicalBySuffix.get(cleaned)\n    if (matches && matches.length === 1) return { succeeded: true, value: matches[0]! }\n  }\n\n  return { succeeded: false, error: `Model is not available: ${cleaned}` }\n}\n\n/** Resolve and return a trimmed string model ID or undefined for invalid or empty input */\nexport function cleanModelId(value: unknown): string | undefined {\n  if (typeof value !== 'string') return undefined\n  const trimmed = value.trim()\n  return trimmed.length > 0 ? trimmed : undefined\n}\n\n/** Validate if a model ID string conforms to length and character format requirements */\nexport function isWellFormedModelId(modelId: string): boolean {\n  if (modelId.length > 200) return false\n  return /^[A-Za-z0-9._/@:-]+$/.test(modelId)\n}\n\n/** Resolve unique catalog IDs associated with a given model including its canonical form if applicable */\nexport function catalogIdsForModel(model: ModelInfo): string[] {\n  const ids = new Set<string>()\n  if (typeof model.id === 'string' && model.id.trim()) ids.add(model.id.trim())\n  if (typeof model.id === 'string' && model.id.trim() && !model.id.includes('/')) {\n    const canonical = canonicalModelId(model)\n    if (canonical.includes('/')) ids.add(canonical)\n  }\n  return [...ids]\n}\n"],"mappings":"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","names":[]}

package/dist/{operations-DLIvvD00.d.ts → operations-ByJ6yXOW.d.ts}

@@ -1,4 +1,4 @@
-import { d as SceneElement, N as NewPageOptions, P as PageBleed, a as PageGuides } from './model-BBwyOuWG.js';
+import { a as SceneElement, N as NewPageOptions, P as PageBleed, b as PageGuides } from './model-DnfO_PdJ.js';
 
 /**
  * The design-canvas operation union — the ONE mutation vocabulary shared by
@@ -35,6 +35,7 @@ type SceneAttrsPatch = Partial<Omit<SceneElement, 'id' | 'kind' | 'children'>> &
     posterSrc?: string;
     fit?: 'fill' | 'cover' | 'contain';
 };
+/** Define an operation to add a scene element to a page with optional index and parent group */
 interface AddElementOperation {
     type: 'add_element';
     pageId: string;
@@ -46,12 +47,14 @@ interface AddElementOperation {
     /** Parent group; omitted → page root. */
     parentGroupId?: string;
 }
+/** Define an operation to update attributes of a specific element on a page */
 interface SetAttrsOperation {
     type: 'set_attrs';
     pageId: string;
     elementId: string;
     attrs: SceneAttrsPatch;
 }
+/** Resolve an operation to reorder an element within its current owner by specifying the target index */
 interface ReorderElementOperation {
     type: 'reorder_element';
     pageId: string;
@@ -59,11 +62,13 @@ interface ReorderElementOperation {
     /** Target index within the element's CURRENT owner (page root or group). */
     toIndex: number;
 }
+/** Resolve deletion of a specific element from a page by its identifiers */
 interface DeleteElementOperation {
     type: 'delete_element';
     pageId: string;
     elementId: string;
 }
+/** Group elements by grouping two or more sibling elements in their current z-order under a new group ID */
 interface GroupElementsOperation {
     type: 'group_elements';
     pageId: string;
@@ -73,11 +78,13 @@ interface GroupElementsOperation {
     groupId: string;
     name?: string;
 }
+/** Resolve an operation to ungroup elements within a specified page and group context */
 interface UngroupElementOperation {
     type: 'ungroup_element';
     pageId: string;
     groupId: string;
 }
+/** Define an operation to add a new page with an optional position and caller-minted page ID */
 interface AddPageOperation {
     type: 'add_page';
     /** Caller-minted page id. */
@@ -86,21 +93,25 @@ interface AddPageOperation {
     /** Position in the page list; omitted → end. */
     index?: number;
 }
+/** Define an operation to duplicate a page with a new caller-specified page ID */
 interface DuplicatePageOperation {
     type: 'duplicate_page';
     sourcePageId: string;
     /** Caller-minted id for the copy; element ids are re-minted server-side. */
     pageId: string;
 }
+/** Represent a delete page operation with a specified page identifier */
 interface DeletePageOperation {
     type: 'delete_page';
     pageId: string;
 }
+/** Represent an operation to reorder a page by moving it to a specified index */
 interface ReorderPageOperation {
     type: 'reorder_page';
     pageId: string;
     toIndex: number;
 }
+/** Define an operation to set or update properties of a page including size, background, and bleed */
 interface SetPagePropsOperation {
     type: 'set_page_props';
     pageId: string;
@@ -111,11 +122,13 @@ interface SetPagePropsOperation {
     /** null clears bleed; omitted leaves unchanged. */
     bleed?: PageBleed | null;
 }
+/** Resolve an operation to set guides on a specific page by its identifier */
 interface SetPageGuidesOperation {
     type: 'set_page_guides';
     pageId: string;
     guides: PageGuides;
 }
+/** Define an operation to bind or unbind a unique slot to an element on a specific page */
 interface BindSlotOperation {
     type: 'bind_slot';
     pageId: string;
@@ -129,16 +142,21 @@ interface ApplyDataOperation {
     type: 'apply_data';
     bindings: Record<string, string>;
 }
+/** Define an operation to set the document title to a specified string */
 interface SetDocumentTitleOperation {
     type: 'set_document_title';
     title: string;
 }
+/** Represent operations that modify scenes by adding, updating, reordering, grouping, or deleting elements and pages */
 type SceneOperation = AddElementOperation | SetAttrsOperation | ReorderElementOperation | DeleteElementOperation | GroupElementsOperation | UngroupElementOperation | AddPageOperation | DuplicatePageOperation | DeletePageOperation | ReorderPageOperation | SetPagePropsOperation | SetPageGuidesOperation | BindSlotOperation | ApplyDataOperation | SetDocumentTitleOperation;
+/** Define a plan summarizing a scene with its description and associated operations */
 interface ScenePlan {
     summary: string;
     operations: SceneOperation[];
 }
+/** Extract the type property from a SceneOperation to represent its operation type */
 type SceneOperationType = SceneOperation['type'];
+/** Define all valid operation types for scene manipulation in the application */
 declare const SCENE_OPERATION_TYPES: readonly SceneOperationType[];
 
-export { type AddElementOperation as A, type BindSlotOperation as B, type DeleteElementOperation as D, type GroupElementsOperation as G, type ReorderElementOperation as R, SCENE_OPERATION_TYPES as S, type UngroupElementOperation as U, type AddPageOperation as a, type ApplyDataOperation as b, type DeletePageOperation as c, type DuplicatePageOperation as d, type ReorderPageOperation as e, type SceneAttrsPatch as f, type SceneOperation as g, type SceneOperationType as h, type ScenePlan as i, type SetAttrsOperation as j, type SetDocumentTitleOperation as k, type SetPageGuidesOperation as l, type SetPagePropsOperation as m };
+export { type AddElementOperation as A, type BindSlotOperation as B, type DeleteElementOperation as D, type GroupElementsOperation as G, type ReorderElementOperation as R, type SceneOperation as S, type UngroupElementOperation as U, type ScenePlan as a, type AddPageOperation as b, type ApplyDataOperation as c, type DeletePageOperation as d, type DuplicatePageOperation as e, type ReorderPageOperation as f, SCENE_OPERATION_TYPES as g, type SceneAttrsPatch as h, type SceneOperationType as i, type SetAttrsOperation as j, type SetDocumentTitleOperation as k, type SetPageGuidesOperation as l, type SetPagePropsOperation as m };