@studio-foundation/contracts 0.13.0 → 0.15.0

package/README.md

@@ -67,7 +67,7 @@ Nothing imports upward. If you find yourself adding a dep here, you're solving t
 | `tool-plugin.ts` | `ToolPluginDef`, `ToolCommandDef`, `ShellExecute`, `BuiltinExecute`, `ParameterDef` |
 | `runner-events.ts` | `RunnerCallbacks`, `ToolCallStartEvent`, `ToolCallCompleteEvent`, `AgentThinkingEvent`, `AgentProgressEvent`, `AgentTokenEvent` |
 | `spawner.ts` | `RunSpawner`, `SpawnConfig`, `SpawnResult` |
-| `integration-plugin.ts` | `IntegrationPluginDef` |
+| `trigger.ts` | `TriggerDef` |
 
 ## Key types
 

package/dist/agent.d.ts

@@ -1,3 +1,13 @@
+/**
+ * What an agent asks the provider to do about prompt caching.
+ *
+ * - `auto` (default) — cache only when the stage is expected to run more than one
+ *   turn against the same prefix, which is what makes a cache write pay for itself.
+ * - `on` — always cache. For a fan-out whose items have been measured to share a
+ *   prefix long enough to beat the write premium.
+ * - `off` — never cache, whatever the stage looks like.
+ */
+export type PromptCacheMode = 'auto' | 'on' | 'off';
 export interface AgentConfig {
     name: string;
     description?: string;
@@ -10,6 +20,8 @@ export interface AgentConfig {
     temperature?: number;
     max_tokens?: number;
     anonymize?: boolean;
+    /** Prompt-cache policy for this agent's calls. Default `auto`. */
+    prompt_cache?: PromptCacheMode;
 }
 /** AgentConfig after defaults have been applied — provider and model are guaranteed. */
 export interface ResolvedAgentConfig extends AgentConfig {

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,wFAAwF;AACxF,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AAEvC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/index.d.ts

@@ -5,10 +5,11 @@ export * from './agent.js';
 export * from './run.js';
 export * from './validation.js';
 export * from './provider.js';
+export * from './usage.js';
 export * from './errors.js';
 export * from './context-pack.js';
 export * from './tool-plugin.js';
 export * from './runner-events.js';
 export * from './spawner.js';
-export * from './integration-plugin.js';
+export * from './trigger.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/index.js

@@ -7,10 +7,11 @@ export * from './agent.js';
 export * from './run.js';
 export * from './validation.js';
 export * from './provider.js';
+export * from './usage.js';
 export * from './errors.js';
 export * from './context-pack.js';
 export * from './tool-plugin.js';
 export * from './runner-events.js';
 export * from './spawner.js';
-export * from './integration-plugin.js';
+export * from './trigger.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AAEpD,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,oDAAoD;AAEpD,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AAEjC,cAAc,oBAAoB,CAAC;AAEnC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/pipeline.d.ts

@@ -123,6 +123,51 @@ export interface MapStage {
      * restart between runs.
      */
     resume?: boolean;
+    /**
+     * Dispatch this fan-out's LLM calls as batches instead of one synchronous
+     * request per item (default: off). `true` takes every default below.
+     *
+     * The items of a fan-out are independent and nothing is waiting on any single
+     * one of them, which is exactly what a vendor batch endpoint is priced for:
+     * Anthropic's Message Batches API bills every token — input, output, cache
+     * write, cache read — at 50% of the synchronous rate, in exchange for up to
+     * 24h to finish. On a bulk stage that is the largest cost lever there is.
+     *
+     * What it changes, and what it does not:
+     *   - Items still run as ordinary child runs. Contracts, RALPH, hooks,
+     *     post-validation and the `resume` cache all behave identically; a cached
+     *     item is simply never dispatched.
+     *   - Validation stays per item, after the batch comes back. An item that
+     *     fails retries into the *next* batch, so rounds shrink instead of the
+     *     retry loop paying full price per item.
+     *   - `concurrency` defaults to `min(items, max_size)` here instead of 1 —
+     *     items must be in flight together to share a batch. An explicit
+     *     `concurrency` is still honoured, and caps the batch at that size.
+     *   - Nothing streams: a batched response arrives whole, so `--live` shows no
+     *     tokens for these items.
+     *   - A provider with no batch endpoint (mock, ollama, claude-code) runs the
+     *     stage exactly as it would without this key — correct, just not cheaper.
+     */
+    batch?: boolean | MapBatchConfig;
+}
+/** Tuning for a `map` stage's batched dispatch. Every field has a default. */
+export interface MapBatchConfig {
+    /** Requests per batch before one is sent without waiting for the rest. Default 500. */
+    max_size?: number;
+    /** How often to ask whether the batch has ended. Default 15000. */
+    poll_interval_ms?: number;
+    /**
+     * Give up on a batch after this long, failing its requests. Default 86400000
+     * (24h — the API's own expiry). A batch has no per-call timeout; this is the
+     * whole-stage budget that replaces one.
+     */
+    max_wait_ms?: number;
+    /**
+     * Send what is parked after this long with no new request arriving, even
+     * while an item is still busy elsewhere. Default 30000, `0` disables it.
+     * Without it one slow item would hold the whole batch.
+     */
+    flush_after_ms?: number;
 }
 /**
  * A call stage: run a named pipeline once, inline, and expose its output to

package/dist/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"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"}

package/dist/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAiLjC,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC"}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAAA,iCAAiC;AA+NjC,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,OAAO,OAAO,IAAI,KAAK,IAAI,QAAQ,IAAI,KAAK,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,OAAO,KAAK,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAoB;IAC9C,OAAO,MAAM,IAAI,KAAK,CAAC;AACzB,CAAC"}

package/dist/provider.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from './usage';
 export interface LLMRequest {
     model: string;
     messages: Message[];
@@ -6,6 +7,15 @@ export interface LLMRequest {
     max_tokens?: number;
     stage_name?: string;
     json_mode?: boolean;
+    /**
+     * Whether the provider should mark this call's stable prefix (system prompt +
+     * tool definitions) as cacheable. A cache write is billed above the plain input
+     * rate and only pays for itself once something reads it back, so a call that
+     * will never have a successor costs MORE with caching on than off. The caller
+     * decides — it is the only party that knows whether a second turn is coming.
+     * Absent means no: providers must not cache speculatively.
+     */
+    cache_prompt?: boolean;
 }
 export interface Message {
     role: 'system' | 'user' | 'assistant';
@@ -19,13 +29,8 @@ export interface LLMResponse {
         arguments: Record<string, unknown>;
     }>;
     finish_reason: string;
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-        cached_input_tokens?: number;
-        cache_creation_tokens?: number;
-    };
+    /** What the call cost, as the provider reported it. See ./usage.ts. */
+    usage?: TokenUsage;
 }
 export interface ToolDefinition {
     name: string;

package/dist/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CAAC;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC,CAAC;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC"}

package/dist/run.d.ts

@@ -1,5 +1,6 @@
 import type { StageStatus } from './stage';
 import type { TaskStatus } from './task';
+import type { TokenUsage } from './usage';
 export type AgentStatus = 'pending' | 'running' | 'success' | 'failed';
 export interface PipelineRun {
     id: string;
@@ -23,6 +24,7 @@ export interface StageRun {
     output?: unknown;
     skipped_reason?: string;
     child_run_id?: string;
+    token_usage?: TokenUsage;
 }
 export interface TaskRun {
     id: string;

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IAIvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IAIxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IAIvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IAIxB,YAAY,CAAC,EAAE,MAAM,CAAC;IAItB,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/spawner.d.ts

@@ -1,13 +1,34 @@
+import type { TokenUsage } from './usage';
+/**
+ * Per-spawn execution overrides. In-process spawners honour them; a remote
+ * spawner ignores them, because they name objects that live in this process.
+ *
+ * Typed as `unknown` on purpose: contracts is a leaf package (INV-04) and the
+ * provider registry lives in runner, so the type cannot be named here. The
+ * in-process spawner casts it back.
+ */
+export interface SpawnOverrides {
+    /**
+     * Replaces the engine's provider registry for this child run and its
+     * descendants. Set by a `map` stage running with `batch:` — the substituted
+     * registry parks the child's LLM calls in the parent's batch window instead
+     * of sending them one by one.
+     */
+    providerRegistry?: unknown;
+}
 export interface SpawnConfig {
     pipeline: string;
     input: Record<string, unknown>;
     parentRunId: string;
     depth: number;
+    overrides?: SpawnOverrides;
 }
 export interface SpawnResult {
     run_id: string;
     status: string;
     output: unknown;
+    /** What the child run spent, summed over its stages. Absent when unreported. */
+    token_usage?: TokenUsage;
 }
 export interface RunSpawner {
     spawnAndWait(config: SpawnConfig): Promise<SpawnResult>;

package/dist/spawner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../src/spawner.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACzD"}
+{"version":3,"file":"spawner.d.ts","sourceRoot":"","sources":["../src/spawner.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,WAAW,CAAC,EAAE,UAAU,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACzD"}

package/dist/trigger.d.ts

@@ -0,0 +1,38 @@
+export interface TriggerDef {
+    name: string;
+    version: number;
+    description?: string;
+    /** Pipeline to launch when the webhook matches. */
+    pipeline: string;
+    /** Omitted entirely, every signed-or-not delivery matches — same as an empty block. */
+    webhook?: {
+        hmac?: {
+            /** Request header carrying the hex signature, e.g. 'x-hub-signature-256'. */
+            header: string;
+            /** Shared secret; `${VAR}` is resolved from the environment at load. */
+            secret: string;
+        };
+        /** Conditions over `payload.<path>`, same syntax as a stage `when:`. All must hold. */
+        when?: string[];
+    };
+    /** Pipeline input, with `{{payload.<path>}}` references. */
+    input?: Record<string, unknown>;
+    /** Run metadata, with `{{payload.<path>}}` references. */
+    meta?: Record<string, unknown>;
+    /** What to show in the trigger log, with `{{payload.<path>}}` references. */
+    log?: {
+        external_id?: string;
+        external_label?: string;
+        external_url?: string;
+    };
+    /**
+     * Command run when a triggered run does not succeed. Values reach it through
+     * the environment (`STUDIO_RUN_ID`, `STUDIO_META`, …), never interpolated into
+     * the command string — the payload that produced them is untrusted.
+     */
+    on_failure?: {
+        command: string;
+        timeout_ms?: number;
+    };
+}
+//# sourceMappingURL=trigger.d.ts.map

package/dist/trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.d.ts","sourceRoot":"","sources":["../src/trigger.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE;YACL,6EAA6E;YAC7E,MAAM,EAAE,MAAM,CAAC;YACf,wEAAwE;YACxE,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC;QACF,uFAAuF;QACvF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;IACF,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,GAAG,CAAC,EAAE;QACJ,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH"}

package/dist/trigger.js

@@ -0,0 +1,6 @@
+// A `.trigger.yaml` — an inbound webhook that launches a pipeline run.
+//
+// Triggers cover the one thing tools and MCP servers cannot: an external system
+// pushing to Studio. Everything a trigger does *outbound* belongs in a tool.
+export {};
+//# sourceMappingURL=trigger.js.map

package/dist/trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.js","sourceRoot":"","sources":["../src/trigger.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,gFAAgF;AAChF,6EAA6E"}

package/dist/usage.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Token counts for a single model.
+ *
+ * The four input/output fields are disjoint, because each is billed at its own
+ * rate — a run that reads 200k tokens from cache and one that sends 200k fresh
+ * differ by an order of magnitude in cost, and a single `prompt_tokens` number
+ * cannot tell them apart. Providers report the split differently (Anthropic
+ * excludes cache counts from its input total, OpenAI includes them); every
+ * Studio provider normalizes to the definitions below.
+ */
+export interface ModelTokenUsage {
+    /** Input tokens billed at full rate — cache reads and writes excluded. */
+    prompt_tokens: number;
+    /** Output tokens generated. */
+    completion_tokens: number;
+    /** Every token the call consumed: prompt + cached + cache-creation + completion. */
+    total_tokens: number;
+    /** Input tokens served from the provider's prompt cache (billed at a discount). */
+    cached_input_tokens?: number;
+    /** Input tokens written to the provider's prompt cache (billed at a premium). */
+    cache_creation_tokens?: number;
+}
+export interface TokenUsage extends ModelTokenUsage {
+    /**
+     * Per-model split of the same counts. One entry for an ordinary call; several
+     * when a single call spans models (the claude CLI reports one per model it
+     * used, subagents included). The top-level counts are always the sum of these.
+     */
+    by_model?: Record<string, ModelTokenUsage>;
+}
+/** A zeroed accumulator. */
+export declare function emptyTokenUsage(): TokenUsage;
+/**
+ * Attach a model name to a set of counts, so the by_model split survives every
+ * later merge. Providers that know which model answered call this instead of
+ * building the map by hand.
+ */
+export declare function withModel(model: string | undefined, counts: ModelTokenUsage): TokenUsage;
+/**
+ * Sum `add` into `target` in place, merging the per-model split. `target` must be
+ * an accumulator you own — `emptyTokenUsage()` or a clone.
+ */
+export declare function accumulateTokenUsage(target: TokenUsage, add: TokenUsage | undefined): TokenUsage;
+/**
+ * Sum any number of usages. Returns undefined when nothing was reported, so an
+ * absent usage stays absent instead of becoming a misleading row of zeros.
+ */
+export declare function sumTokenUsage(usages: Array<TokenUsage | undefined>): TokenUsage | undefined;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iFAAiF;IACjF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,UAAW,SAAQ,eAAe;IACjD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC5C;AAED,4BAA4B;AAC5B,wBAAgB,eAAe,IAAI,UAAU,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,UAAU,CAGxF;AAcD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAehG;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,CAAC,GAAG,UAAU,GAAG,SAAS,CAM3F"}

package/dist/usage.js

@@ -0,0 +1,68 @@
+// Token accounting — the shape every provider reports and every consumer sums.
+//
+// One type, three hops: a provider fills it per LLM call, the runner accumulates
+// it across the turns of one agent run, the engine stamps it on the stage and the
+// CLI writes it to the run JSONL. Measuring what a run cost is then a `jq` pass
+// over `.studio/runs/<run>.jsonl`, not a correlation of provider session files
+// against stage timestamps.
+/** A zeroed accumulator. */
+export function emptyTokenUsage() {
+    return { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+}
+/**
+ * Attach a model name to a set of counts, so the by_model split survives every
+ * later merge. Providers that know which model answered call this instead of
+ * building the map by hand.
+ */
+export function withModel(model, counts) {
+    if (!model)
+        return { ...counts };
+    return { ...counts, by_model: { [model]: { ...counts } } };
+}
+function addInto(target, add) {
+    target.prompt_tokens += add.prompt_tokens;
+    target.completion_tokens += add.completion_tokens;
+    target.total_tokens += add.total_tokens;
+    if (add.cached_input_tokens !== undefined) {
+        target.cached_input_tokens = (target.cached_input_tokens ?? 0) + add.cached_input_tokens;
+    }
+    if (add.cache_creation_tokens !== undefined) {
+        target.cache_creation_tokens = (target.cache_creation_tokens ?? 0) + add.cache_creation_tokens;
+    }
+}
+/**
+ * Sum `add` into `target` in place, merging the per-model split. `target` must be
+ * an accumulator you own — `emptyTokenUsage()` or a clone.
+ */
+export function accumulateTokenUsage(target, add) {
+    if (!add)
+        return target;
+    addInto(target, add);
+    if (add.by_model) {
+        target.by_model ??= {};
+        for (const [model, counts] of Object.entries(add.by_model)) {
+            const existing = target.by_model[model];
+            if (existing) {
+                addInto(existing, counts);
+            }
+            else {
+                target.by_model[model] = { ...counts };
+            }
+        }
+    }
+    return target;
+}
+/**
+ * Sum any number of usages. Returns undefined when nothing was reported, so an
+ * absent usage stays absent instead of becoming a misleading row of zeros.
+ */
+export function sumTokenUsage(usages) {
+    const reported = usages.filter((u) => u !== undefined);
+    if (reported.length === 0)
+        return undefined;
+    const total = emptyTokenUsage();
+    for (const usage of reported)
+        accumulateTokenUsage(total, usage);
+    return total;
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,iFAAiF;AACjF,kFAAkF;AAClF,gFAAgF;AAChF,+EAA+E;AAC/E,4BAA4B;AAkC5B,4BAA4B;AAC5B,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,aAAa,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAyB,EAAE,MAAuB;IAC1E,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IACjC,OAAO,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,OAAO,CAAC,MAAuB,EAAE,GAAoB;IAC5D,MAAM,CAAC,aAAa,IAAI,GAAG,CAAC,aAAa,CAAC;IAC1C,MAAM,CAAC,iBAAiB,IAAI,GAAG,CAAC,iBAAiB,CAAC;IAClD,MAAM,CAAC,YAAY,IAAI,GAAG,CAAC,YAAY,CAAC;IACxC,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,CAAC,mBAAmB,GAAG,CAAC,MAAM,CAAC,mBAAmB,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,mBAAmB,CAAC;IAC3F,CAAC;IACD,IAAI,GAAG,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,CAAC,qBAAqB,GAAG,CAAC,MAAM,CAAC,qBAAqB,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,qBAAqB,CAAC;IACjG,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkB,EAAE,GAA2B;IAClF,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC;IACxB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrB,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,MAAM,CAAC,QAAQ,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,QAAQ,EAAE,CAAC;gBACb,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAC5B,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAqC;IACjE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAmB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACxE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,QAAQ;QAAE,oBAAoB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@studio-foundation/contracts",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Shared TypeScript types and interfaces for Studio packages",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [

package/dist/integration-plugin.d.ts

@@ -1,35 +0,0 @@
-export interface IntegrationPluginDef {
-    name: string;
-    version: number;
-    description?: string;
-    config?: {
-        required?: string[];
-        optional?: Record<string, unknown>;
-    };
-    events?: {
-        consumes?: string[];
-        emits?: string[];
-    };
-    test?: {
-        type: 'http';
-        endpoint: string;
-        method?: 'GET' | 'POST';
-        /** e.g. "bearer:${LINEAR_API_KEY}" — resolved before use */
-        auth?: string;
-        body?: string;
-        expect?: {
-            status?: number;
-        };
-    };
-    webhook?: {
-        hmac?: {
-            header: string;
-            secret_env: string;
-        };
-        handler: string;
-    };
-    on_failure?: {
-        handler: string;
-    };
-}
-//# sourceMappingURL=integration-plugin.d.ts.map

package/dist/integration-plugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"integration-plugin.d.ts","sourceRoot":"","sources":["../src/integration-plugin.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KAClB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QACxB,4DAA4D;QAC5D,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC9B,CAAC;IACF,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH"}

package/dist/integration-plugin.js

@@ -1,3 +0,0 @@
-// contracts/src/integration-plugin.ts
-export {};
-//# sourceMappingURL=integration-plugin.js.map

package/dist/integration-plugin.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"integration-plugin.js","sourceRoot":"","sources":["../src/integration-plugin.ts"],"names":[],"mappings":"AAAA,sCAAsC"}