@yaklabs-ai/plugin-sdk 0.14.1 → 0.15.1

package/dist/kay-app.d.ts

@@ -1,3 +1,4 @@
+import { pathToFileURL } from 'node:url';
 import type { StatementSync } from 'node:sqlite';
 import { z } from 'zod';
 
@@ -78,6 +79,8 @@ export declare interface AgentToolResult<T = JsonValue_2 | undefined> {
      * error, but `details` and `structuredContent` are kept for the UI and programmatic callers.
      */
     isError?: boolean;
+    /** Classification for an `isError` result; the host validates it and stamps identity and attribution. */
+    failure?: ToolCallFailure;
     /**
      * Hint that the agent should stop after the current tool batch.
      * Early termination only happens when every finalized tool result in the batch sets this to true.
@@ -296,6 +299,12 @@ declare interface BackgroundTaskAdoptOptions {
     readonly ownerId?: string;
     readonly inspect?: BackgroundTaskInspector;
     readonly meta?: Readonly<Record<string, unknown>>;
+    /**
+     * The task's owner waits for its result: the work was meant to finish and report back (a build,
+     * a test run). Absent or false: nothing waits on it (a dev server, a watcher). The kernel only
+     * carries this fact on the task's snapshot; what waiting means is the host's to decide.
+     */
+    readonly awaitsResult?: boolean;
     /** Scoped settlement hook for the task created by this adoption only. */
     readonly onSettled?: (completion: BackgroundTaskCompletion) => void;
 }
@@ -370,6 +379,8 @@ declare interface BackgroundTaskSnapshot {
     readonly startedAtMs: number;
     readonly updatedAtMs: number;
     readonly meta?: Readonly<Record<string, unknown>>;
+    /** The owner waits for this task's result; see `BackgroundTaskAdoptOptions.awaitsResult`. */
+    readonly awaitsResult?: boolean;
 }
 
 declare type BackgroundTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
@@ -843,7 +854,7 @@ declare interface DecideChoiceQuestion<L extends string = string> {
 /** What a question asks: text, or a JSON object the client sends as its JSON text. */
 declare type DecideInstructions = string | object;
 
-declare type DecideModelId = "jev" | "clef" | "clef-flash";
+declare type DecideModelId = "jev" | "clef" | "clef-flash" | "gpt-6-luna";
 
 declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion | DecideScoreQuestion;
 
@@ -851,10 +862,10 @@ declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion | Decide
 declare type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
 
 declare interface DecideRequest<Q extends DecideQuestions = DecideQuestions> {
-    /** Defaults to `jev`. */
-    readonly model?: DecideModelId;
+    readonly model: DecideModelId;
     readonly state: DecideState;
     readonly questions: Q;
+    readonly image?: SystemOneImage;
 }
 
 declare interface DecideScoreAnswer {
@@ -1235,7 +1246,10 @@ declare interface ExtensionAuthContext {
 
 /** Optional extension-facing APIs for background task orchestration. */
 declare interface ExtensionBackgroundTasksApi {
-    adopt(taskKind: BackgroundTaskKind, label: string, run: BackgroundTaskRun, options?: BackgroundTaskAdoptOptions): string;
+    adopt(taskKind: BackgroundTaskKind, label: string, run: BackgroundTaskRun, options?: BackgroundTaskAdoptOptions & {
+        readonly awaitsResult?: false;
+    }): string;
+    adopt(taskKind: BackgroundTaskKind, label: string, run: BackgroundTaskRun, options: BackgroundTaskAdoptOptions): string | Promise<string>;
     list(): readonly BackgroundTaskSnapshot[];
     get(taskId: string): BackgroundTaskSnapshot | undefined;
 }
@@ -1836,7 +1850,7 @@ declare type JsonValue_4 = null | boolean | number | string | readonly JsonValue
  * the union and not to this list, so the next kind cannot repeat that bug
  * quietly.
  */
-export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "occurrence", "delayed-occurrence"];
+export declare const KAY_APP_AUTOMATION_CONDITION_KINDS: readonly ["time", "uri-change", "plugin-event", "occurrence", "delayed-occurrence"];
 
 /** Maximum UTF-8 JSON size of one plugin app-data live change. */
 export declare const KAY_APP_DATA_CHANGE_MAX_BYTES: number;
@@ -2093,7 +2107,10 @@ export declare interface KayAppAccountProfileUpdate {
     readonly displayName: string;
 }
 
-/** Owned services use local IDs; omitted scheme searches all admitted schemes. */
+/**
+ * Service/scheme IDs are local when owned, globally qualified when consumed.
+ * Omitting scheme searches all admitted schemes.
+ */
 export declare interface KayAppAccountRequest {
     readonly serviceId: string;
     readonly schemeId?: string;
@@ -2363,15 +2380,20 @@ export declare interface KayAppAuth {
     /** Resolve a granted credential for a declared purpose. */
     resolve(request: KayAppResolveCredentialRequest): Promise<KayAppResolvedCredential>;
     /**
-     * Enumerate an owned service under an explicit list grant. Includes accounts needing repair.
+     * Enumerate an owned or consumed service under an explicit list grant in
+     * permissions.byTarget["kay.app"].auth. Consumption or resolve alone does not allow listing;
+     * shared-identity services also require auth.shared-identity authorization.
+     * Includes accounts needing repair within admitted schemes, without broadening resolve grants.
      * Never resolves, decrypts secret material, refreshes, or calls a provider. Invalid or
      * unauthorized requests reject; an authorized service with no accounts returns an empty list.
      */
     listAccounts(request: KayAppAccountRequest): Promise<readonly KayAppAccountSummary[]>;
     /**
      * Stored availability, not proof that a provider request will authenticate. False for no
-     * matching account or only revoked/needs-reauth accounts. Accepts list permission or existing
-     * resolve permission within its account bounds. Storage and authorization failures reject.
+     * matching account or only revoked/needs-reauth accounts. Uses explicit list permission for
+     * owned or consumed services when present, otherwise resolve permission within its account
+     * bounds. Never resolves, decrypts secrets, refreshes, or calls a provider.
+     * Storage and authorization failures reject.
      */
     has(request: KayAppAccountRequest): Promise<boolean>;
 }
@@ -2451,7 +2473,7 @@ export declare interface KayAppAutomationBinding {
     readonly scriptLastError?: string;
 }
 
-export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditionInput, {
+export declare type KayAppAutomationCondition = KayAppAutomationPluginEventCondition | Extract<KayAppAutomationConditionInput, {
     readonly kind: "time";
 }> | KayAppAutomationUriChangeCondition | {
     readonly kind: "occurrence";
@@ -2473,7 +2495,7 @@ export declare type KayAppAutomationCondition = Extract<KayAppAutomationConditio
     readonly guard?: "session-idle";
 };
 
-export declare type KayAppAutomationConditionInput = {
+export declare type KayAppAutomationConditionInput = KayAppAutomationPluginEventCondition | {
     readonly kind: "time";
     readonly schedule: {
         readonly kind: "every";
@@ -2585,6 +2607,22 @@ export declare interface KayAppAutomationExternalResourceItem {
 export declare type KayAppAutomationFactSource = "run-settled" | "tool-used" | "tool-failed";
 
 export declare type KayAppAutomationMatch = {
+    readonly kind: "plugin-event";
+    readonly event: {
+        readonly id: string;
+        readonly type: string;
+        readonly version: number;
+        readonly uri: string;
+        readonly occurredAt: string;
+        readonly publishedAt: string;
+        readonly source: {
+            readonly layer: "runtime";
+            readonly pluginId: string;
+            readonly poller?: string | undefined;
+            readonly runId?: string | undefined;
+        };
+    };
+} | {
     readonly kind: "time";
     readonly scheduledAtMs: number;
 } | {
@@ -2626,6 +2664,16 @@ export declare type KayAppAutomationMatch = {
     readonly requestedBy?: "user" | "agent" | undefined;
 };
 
+/** Match any listed type; filters use strict equality or scalar-list containment. */
+export declare interface KayAppAutomationPluginEventCondition {
+    readonly kind: "plugin-event";
+    readonly events: readonly string[];
+    readonly where?: readonly {
+        readonly path: string;
+        readonly equals: string | number | boolean;
+    }[];
+}
+
 /**
  * One URI a run produced: every URI its successful `write` and `edit` calls
  * changed, every URI a tool declared it created or updated, and every row
@@ -3878,11 +3926,11 @@ export declare interface KayAppPluginApi {
      */
     readonly sessionEvents: KayAppSessionEvents;
     /**
-     * Grant-gated time-triggered workflow registration. PRESENT ONLY for a plugin holding the
-     * `workflows.define` claim in the user's grant ledger — no manifest request and no source-class
-     * gate; `undefined` otherwise. Same deny-by-default rule as {@link corpus}: an ungranted plugin
-     * cannot even reference the capability, so guard with `if (app.workflows === undefined) return;`
-     * rather than assuming it is there.
+     * Grant-gated time-triggered workflow registration. Present for a plugin the host has a workflow
+     * namespace for; `undefined` otherwise. The first `define` asks for the `workflows.define` claim
+     * in the user's grant ledger — no manifest request and no source-class gate — and it is decided
+     * once `activate()` resolves: an ungranted plugin does not start until the user allows it. A
+     * plugin that defines no workflow is never asked.
      */
     readonly workflows?: KayAppWorkflows;
     /**
@@ -3988,12 +4036,7 @@ export declare interface KayAppPluginApi {
 }
 
 export declare interface KayAppPluginEvents {
-    publish(localId: string, payload: unknown, options?: {
-        readonly subject?: {
-            readonly kind: string;
-            readonly id?: string;
-        };
-    }): void;
+    publish(localId: string, input: PluginEventPublishInput): void;
 }
 
 export declare type KayAppProcessingSpeed = "standard" | "fast";
@@ -4126,12 +4169,12 @@ export declare interface KayAppRepos {
 
 /** What the plugin is asking for, and what it intends to do with it. */
 export declare interface KayAppResolveCredentialRequest {
-    /** An auth service this plugin's own manifest declares, by its LOCAL id. */
+    /** A granted service: local ID when owned, globally qualified ID when consumed. */
     readonly serviceId: string;
-    /** Exact scheme to require; omit to resolve the service's sole connected scheme. */
+    /** Local scheme ID when owned, globally qualified when consumed; omit for the sole connected scheme. */
     readonly schemeId?: string;
     /**
-     * One of the `purposes` the declared service lists. The host pins the resolved grant to it, so a
+     * One of the service's `purposes` admitted by the manifest grant. The host pins the grant to it, so a
      * credential taken for `"transcription"` cannot be replayed for anything else.
      */
     readonly purpose: string;
@@ -4140,8 +4183,8 @@ export declare interface KayAppResolveCredentialRequest {
 /**
  * ---
  * responsibility: The plugin-facing credential surface of the `kay.app` target SDK. A daemon-hosted
- *   plugin resolves the credential for an auth service **it declared in its own manifest**, so a
- *   cloud adapter's secret is read where the work happens and never crosses a process boundary.
+ *   plugin lists account metadata or resolves credentials for an owned or consumed auth service
+ *   under explicit grants. Credential material is read where the work happens.
  * owns:
  *   - {@link KayAppAuth}, {@link KayAppResolvedCredential}.
  * does_not_own:
@@ -4152,8 +4195,8 @@ export declare interface KayAppResolveCredentialRequest {
  * ## Deny-by-default
  *
  * `KayAppPluginApi.auth` is **present only for plugins the host grants** (`auth.operations`
- * containing `"list"` or `"resolve"` in `permissions.byTarget["kay.app"]`, against a service the manifest
- * declares) and `undefined` otherwise — an ungranted plugin cannot even reference the capability.
+ * containing `"list"` or `"resolve"` in `permissions.byTarget["kay.app"]`, against an owned or consumed
+ * service) and `undefined` otherwise — an ungranted plugin cannot even reference the capability.
  * This mirrors `KayAppPluginApi.corpus`, and it is the rule for every capability behind a grant:
  * never hand a plugin an object whose grant is decorative.
  *
@@ -5967,6 +6010,8 @@ export declare interface KayAppWhiteboardTypes {
  *   different process. Anything you need later belongs in a step's return value.
  */
 export declare interface KayAppWorkflowContext {
+    /** State from the last successful run; undefined until a run saves it. */
+    readonly state: JsonValue | undefined;
     readonly automationId: string;
     readonly runId: string;
     readonly match: Extract<KayAppAutomationMatch, {
@@ -6039,6 +6084,8 @@ export declare interface KayAppWorkflowDefinition {
         readonly kind: "time";
     }>;
     readonly run: (context: KayAppWorkflowContext) => Promise<{
+        /** Replacement JSON state, at most 64 KiB; omission keeps the previous value. */
+        readonly state?: JsonValue | undefined;
         readonly summary: KayAppRunSummary;
         readonly produced?: KayAppRunProduced;
         readonly effect?: KayAppRunEffect;
@@ -7149,6 +7196,8 @@ declare function Partial_2<Type extends TSchema>(type: Type, options?: TSchemaOp
 /** Creates a deferred Partial action. */
 declare function PartialDeferred<Type extends TSchema>(type: Type, options?: TSchemaOptions): TPartialDeferred<Type>;
 
+export { pathToFileURL }
+
 declare const Pattern: (input: string) => [unknown, string] | [];
 
 declare const PatternBase: (input: string) => [unknown, string] | [];
@@ -7309,6 +7358,42 @@ export declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
 
 export declare type PluginAgentDefinitionPermissionRule = z.infer<typeof PluginAgentDefinitionPermissionRule>;
 
+export declare const PluginEventEnvelope: z.ZodObject<{
+    id: z.ZodString;
+    localId: z.ZodString;
+    type: z.ZodString;
+    version: z.ZodNumber;
+    uri: z.ZodString;
+    related: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    key: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodISODateTime;
+    publishedAt: z.ZodISODateTime;
+    source: z.ZodObject<{
+        poller: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+        layer: z.ZodLiteral<"runtime">;
+        pluginId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    payload: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+}, z.core.$strict>;
+
+export declare type PluginEventEnvelope = z.infer<typeof PluginEventEnvelope>;
+
+export declare const PluginEventPublishInput: z.ZodObject<{
+    uri: z.ZodString;
+    related: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>>;
+    key: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodOptional<z.ZodISODateTime>;
+    source: z.ZodOptional<z.ZodObject<{
+        poller: z.ZodOptional<z.ZodString>;
+        runId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    payload: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+}, z.core.$strict>;
+
+export declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
+
 declare const Properties: (input: string) => [unknown, string] | [];
 
 declare function PropertiesMapping(input: [unknown, unknown, unknown]): unknown;
@@ -8201,6 +8286,7 @@ declare const SessionCreator: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cron: "cron";
         occurrence: "occurrence";
         "uri-change": "uri-change";
+        "plugin-event": "plugin-event";
         manual: "manual";
     }>;
 }, z.core.$strict>, z.ZodObject<{
@@ -8292,6 +8378,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             cron: "cron";
             occurrence: "occurrence";
             "uri-change": "uri-change";
+            "plugin-event": "plugin-event";
             manual: "manual";
         }>;
     }, z.core.$strict>, z.ZodObject<{
@@ -8605,7 +8692,7 @@ declare interface SystemOneClient {
     decide<const Q extends DecideQuestions>(request: DecideRequest<Q>, options?: SystemOneCallOptions): Promise<Decision<Q>>;
     extract<const F extends ExtractFields>(request: ExtractRequest<F>, options?: SystemOneCallOptions): Promise<Extraction<F>>;
     /** Whether some provider in the current order can serve `(kind, model)`. Never rejects. */
-    availability(kind: SystemOneKind, model?: SystemOneModelId): Promise<Availability>;
+    availability(kind: SystemOneKind, model: SystemOneModelId): Promise<Availability>;
 }
 
 /**
@@ -8640,6 +8727,12 @@ declare type SystemOneFailureCause = {
     readonly kind: "invalid-answer";
 };
 
+/** One PNG attachment. `data` is padded base64, without a data-URL prefix. */
+declare interface SystemOneImage {
+    readonly mimeType: "image/png";
+    readonly data: string;
+}
+
 /**
  * ---
  * responsibility: The data shapes of the System One surface: models, the decide and extract
@@ -10833,6 +10926,14 @@ declare interface Tool<TParameters extends TSchema = TSchema> {
     constrainedSampling?: false | ConstrainedSamplingConfig;
 }
 
+/**
+ * The closed vocabulary of tool call failure codes. The engine and the tools
+ * mint only these; a returned failure with a code outside it is not a
+ * classification (the engine records the rejection on an unexplained failure),
+ * and a stored record with one reads as none.
+ */
+declare const TOOL_CALL_FAILURE_CODES: readonly ["tool.invalid_input", "tool.blocked", "tool.cancelled", "tool.timeout", "tool.not_found", "tool.unavailable", "tool.execution_failed", "provider.http", "provider.api", "provider.transport", "uri.not_found", "uri.unsupported_operation", "uri.not_connected", "uri.auth_unavailable", "permission.denied", "edit.empty_edits", "edit.text_not_found", "edit.text_not_unique", "edit.empty_old_text", "edit.overlapping_edits", "edit.no_change"];
+
 /**
  * ---
  * responsibility: The declarative permission classification a tool carries on its definition
@@ -10877,6 +10978,56 @@ declare interface ToolCall {
     argumentsError?: string;
 }
 
+/**
+ * The lane's classification of why one tool invocation failed: a searchable
+ * machine code and the cause the tool or engine classified at execution.
+ */
+declare interface ToolCallFailure extends ToolCallFailureCause {
+    readonly code: ToolCallFailureCode;
+}
+
+declare type ToolCallFailureCause = z.infer<typeof toolCallFailureCauseSchema>;
+
+declare const toolCallFailureCauseSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        cancelled: "cancelled";
+        timeout: "timeout";
+        unknown: "unknown";
+        provider: "provider";
+        "invalid-input": "invalid-input";
+        "not-connected": "not-connected";
+        "unsupported-operation": "unsupported-operation";
+        "not-found": "not-found";
+        permission: "permission";
+        unavailable: "unavailable";
+    }>;
+    retryable: z.ZodBoolean;
+    action: z.ZodEnum<{
+        unknown: "unknown";
+        none: "none";
+        retry: "retry";
+        "correct-input": "correct-input";
+        connect: "connect";
+    }>;
+    details: z.ZodOptional<z.ZodObject<{
+        moduleId: z.ZodOptional<z.ZodString>;
+        toolOwnerId: z.ZodOptional<z.ZodString>;
+        operation: z.ZodOptional<z.ZodString>;
+        uri: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        validationField: z.ZodOptional<z.ZodString>;
+        errorName: z.ZodOptional<z.ZodString>;
+        errorCode: z.ZodOptional<z.ZodString>;
+        providerCode: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        editIndex: z.ZodOptional<z.ZodNumber>;
+        occurrences: z.ZodOptional<z.ZodNumber>;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+declare type ToolCallFailureCode = (typeof TOOL_CALL_FAILURE_CODES)[number];
+
 /** A call to judge with {@link ToolContext.checkToolCallPermission}. */
 declare interface ToolCallPermissionCheck {
     readonly toolName: string;
@@ -11078,6 +11229,14 @@ export declare type ToolParametersWire = unknown;
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
 export declare interface ToolPermissionHint {
+    /**
+     * Names this exact call for the approval card, from its validated input: a title and optional
+     * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
+     * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
+     * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
+     * unsafe string costs the description and the call is asked about as before.
+     */
+    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -11204,6 +11363,16 @@ export declare interface ToolPermissionHint {
     readonly defaultPermission?: "allow" | "ask" | "never";
 }
 
+/** What {@link ToolPermissionHint.describePreview} answers. */
+declare interface ToolPreviewDescription {
+    readonly title: string;
+    readonly description?: string;
+    readonly fields?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+}
+
 declare interface ToolReference {
     name: string;
 }

package/dist/kay-app.js

@@ -163,6 +163,9 @@ function invalidObservation(input) {
   };
 }
 
+// packages/plugin-sdk/dist/kay-app/index.js
+import { pathToFileURL } from "node:url";
+
 // packages/herd-uri/dist/errors.js
 var UriError = class extends Error {
 };
@@ -441,6 +444,7 @@ function isRetryable(result) {
 var KAY_APP_AUTOMATION_CONDITION_KINDS = [
   "time",
   "uri-change",
+  "plugin-event",
   "occurrence",
   "delayed-occurrence"
 ];
@@ -537,6 +541,7 @@ export {
   invalidObservation,
   isRetryable,
   parseLineSelector,
+  pathToFileURL,
   payload,
   transcriptMessageText,
   transcriptMessageTexts,

package/dist/system-one.d.ts

@@ -42,7 +42,7 @@ export declare interface DecideChoiceQuestion<L extends string = string> {
 /** What a question asks: text, or a JSON object the client sends as its JSON text. */
 export declare type DecideInstructions = string | object;
 
-export declare type DecideModelId = "jev" | "clef" | "clef-flash";
+export declare type DecideModelId = "jev" | "clef" | "clef-flash" | "gpt-6-luna";
 
 export declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion | DecideScoreQuestion;
 
@@ -50,10 +50,10 @@ export declare type DecideQuestion = DecideBoolQuestion | DecideChoiceQuestion |
 export declare type DecideQuestions = Readonly<Record<string, DecideQuestion>>;
 
 export declare interface DecideRequest<Q extends DecideQuestions = DecideQuestions> {
-    /** Defaults to `jev`. */
-    readonly model?: DecideModelId;
+    readonly model: DecideModelId;
     readonly state: DecideState;
     readonly questions: Q;
+    readonly image?: SystemOneImage;
 }
 
 export declare interface DecideScoreAnswer {
@@ -243,7 +243,7 @@ export declare interface SystemOneClient {
     decide<const Q extends DecideQuestions>(request: DecideRequest<Q>, options?: SystemOneCallOptions): Promise<Decision<Q>>;
     extract<const F extends ExtractFields>(request: ExtractRequest<F>, options?: SystemOneCallOptions): Promise<Extraction<F>>;
     /** Whether some provider in the current order can serve `(kind, model)`. Never rejects. */
-    availability(kind: SystemOneKind, model?: SystemOneModelId): Promise<SystemOneAvailability>;
+    availability(kind: SystemOneKind, model: SystemOneModelId): Promise<SystemOneAvailability>;
 }
 
 /**
@@ -297,6 +297,12 @@ export declare type SystemOneFailureCause = {
     readonly kind: "invalid-answer";
 };
 
+/** One PNG attachment. `data` is padded base64, without a data-URL prefix. */
+export declare interface SystemOneImage {
+    readonly mimeType: "image/png";
+    readonly data: string;
+}
+
 /**
  * ---
  * responsibility: The data shapes of the System One surface: models, the decide and extract

package/dist/system-one.js

@@ -23,20 +23,6 @@ function isSystemOneError(error) {
   return error instanceof SystemOneError;
 }
 
-// packages/system-one/dist/models.js
-var DEFAULT_DECIDE_MODEL = "jev";
-var SYSTEM_ONE_LIMITS = {
-  /** The serialized request body, in bytes. */
-  maxBodyBytes: 64 * 1024,
-  maxQuestions: 64,
-  maxFields: 32,
-  minChoiceOptions: 2,
-  maxChoiceOptions: 255,
-  minScoreLevels: 2,
-  maxScoreLevels: 10,
-  maxForecastHorizon: 64
-};
-
 // packages/system-one/dist/unavailable.js
 var NOT_SERVED = {
   available: false,
@@ -48,7 +34,7 @@ function createUnavailableSystemOneClient() {
     decide(request) {
       return Promise.reject(new SystemOneError({
         kind: "decide",
-        model: request.model ?? DEFAULT_DECIDE_MODEL,
+        model: request.model,
         cause: { kind: "not-served" }
       }));
     },
@@ -62,6 +48,22 @@ function createUnavailableSystemOneClient() {
     availability: () => Promise.resolve(NOT_SERVED)
   };
 }
+
+// packages/system-one/dist/models.js
+var SYSTEM_ONE_LIMITS = {
+  /** The serialized state and questions, in bytes; images have a separate budget. */
+  maxBodyBytes: 64 * 1024,
+  maxImageBytes: 4 * 1024 * 1024,
+  maxImagePixels: 16e6,
+  maxImageBodyBytes: 6 * 1024 * 1024,
+  maxQuestions: 64,
+  maxFields: 32,
+  minChoiceOptions: 2,
+  maxChoiceOptions: 255,
+  minScoreLevels: 2,
+  maxScoreLevels: 10,
+  maxForecastHorizon: 64
+};
 export {
   SystemOneError,
   createUnavailableSystemOneClient,

package/dist/transcript.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 
+export declare const ATTACHMENTS_CUSTOM_TYPE = "attachments";
+
 /**
  * The ids on a session's active branch: the leaf chain walked parent-ward from
  * the tip, which a trailing `leaf` marker moves. Empty for an empty log.
@@ -43,6 +45,36 @@ export declare function matchesWorkBlock(coverage: WorkBlockCoverage, toolResult
  */
 export declare const NON_ACTIVITY_TOOL_NAMES: readonly string[];
 
+/**
+ * What a run did to a URI. The words match the automation run wire's artifact actions. When one
+ * run both creates and updates a URI, the reader reports `created`.
+ */
+declare type ProducedResourceAction = "created" | "updated";
+
+/** One URI a tool call created or updated as a side effect. */
+declare interface ProducedResourceDeclaration {
+    /** A `scheme://…` URI or an absolute local file path, compared as an exact string. */
+    readonly uri: string;
+    readonly action: ProducedResourceAction;
+}
+
+/**
+ * One tool result's declarations. `absent` covers every result that makes no claim, including a
+ * non-object `details` and an empty list. `malformed` means a claim was made that cannot be
+ * trusted; the reader reports a gap for it instead of keeping the parts that look valid.
+ */
+declare type ProducedResourceDeclarationsRead = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "malformed";
+} | {
+    readonly kind: "declared";
+    readonly resources: readonly ProducedResourceDeclaration[];
+};
+
+/** Read the declarations that one persisted tool result's `details` carries. */
+export declare function readProducedResourceDeclarations(details: unknown): ProducedResourceDeclarationsRead;
+
 /**
  * The daemon's own run-start record. A run's entries begin here, before the
  * user message that opened it.

package/dist/transcript.js

@@ -94,7 +94,47 @@ var NON_ACTIVITY_TOOL_NAMES = [
 ];
 var WORK_HEADLINE_MIN_CHARS = 12;
 var WORK_HEADLINE_MAX_CHARS = 90;
+
+// packages/herd-transcript/dist/context-messages.js
+var ATTACHMENTS_CUSTOM_TYPE = "attachments";
+
+// packages/herd-uri/dist/produced-resources.js
+var PRODUCED_RESOURCES_DETAILS_KEY = "producedResources";
+var ABSENT = { kind: "absent" };
+var MALFORMED = { kind: "malformed" };
+var SCHEME_URI = /^[a-z][a-z0-9+.-]*:\/\/./;
+var WINDOWS_ABSOLUTE_PATH = /^[A-Za-z]:[\\/]./;
+function isProducedResourceUri(value) {
+  if (typeof value !== "string" || value.trim() !== value)
+    return false;
+  return SCHEME_URI.test(value) || value.startsWith("/") && value.length > 1 || WINDOWS_ABSOLUTE_PATH.test(value);
+}
+function isProducedResourceDeclaration(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 2 || !keys.includes("uri") || !keys.includes("action")) {
+    return false;
+  }
+  const record = value;
+  return isProducedResourceUri(record.uri) && (record.action === "created" || record.action === "updated");
+}
+function readProducedResourceDeclarations(details) {
+  if (typeof details !== "object" || details === null || Array.isArray(details) || !Object.hasOwn(details, PRODUCED_RESOURCES_DETAILS_KEY)) {
+    return ABSENT;
+  }
+  const claimed = details[PRODUCED_RESOURCES_DETAILS_KEY];
+  if (!Array.isArray(claimed))
+    return MALFORMED;
+  if (claimed.length === 0)
+    return ABSENT;
+  if (!claimed.every(isProducedResourceDeclaration))
+    return MALFORMED;
+  return { kind: "declared", resources: claimed };
+}
 export {
+  ATTACHMENTS_CUSTOM_TYPE,
   NON_ACTIVITY_TOOL_NAMES,
   RUN_STARTED_CUSTOM_TYPE,
   RUN_TERMINAL_CUSTOM_TYPE,
@@ -105,6 +145,7 @@ export {
   branchEntryIds,
   customEntriesFromEntries,
   matchesWorkBlock,
+  readProducedResourceDeclarations,
   turnSegments,
   workBlockCoverage,
   workBlockKey