@yaklabs-ai/plugin-sdk 0.14.0 → 0.15.0

package/dist/kay-agent.d.ts

@@ -128,6 +128,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.
@@ -305,6 +307,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;
 }
@@ -354,6 +362,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";
@@ -768,7 +778,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;
 
@@ -776,10 +786,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 {
@@ -1179,7 +1189,10 @@ export 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;
 }
@@ -2022,8 +2035,8 @@ export declare class KayAgentCapabilityError extends Error {
  */
 export declare interface KayAgentEvents {
     /**
-     * Publish one event the plugin declares in its `kay.app` `eventDefinitions`, with a payload that
-     * matches that definition's `payloadSchema`.
+     * Publish one event the plugin declares in its `kay.app` `eventDefinitions`, with its resource URI and optional
+     * payload matching that definition's `payloadSchema` when declared.
      *
      * The host stamps the publisher (this plugin) and the session this activation belongs to; the
      * plugin names neither. Fire-and-forget: it returns nothing and never throws. A publish the host
@@ -2031,7 +2044,7 @@ export declare interface KayAgentEvents {
      * is reported to the host's diagnostics and dropped, so the work that raised the event never
      * fails because the event did not go out.
      */
-    publish(localId: string, payload: unknown): void;
+    publish(localId: string, input: PluginEventPublishInput): void;
 }
 
 /** This plugin's folder in the session family's shared Whiteboard. */
@@ -2856,16 +2869,16 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         responseSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, unknown>>>>;
                     }, z.core.$strict>>>;
                     uriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        localId: z.ZodString;
                         displayName: z.ZodOptional<z.ZodString>;
                         schemes: z.ZodArray<z.ZodString>;
-                        localId: z.ZodString;
                     }, z.core.$strict>>>;
                     dataSources: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
                         scope: z.ZodEnum<{
                             session: "session";
-                            account: "account";
                             runtime: "runtime";
+                            account: "account";
                         }>;
                         snapshot: z.ZodObject<{
                             version: z.ZodNumber;
@@ -2915,7 +2928,9 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         displayName: z.ZodOptional<z.ZodString>;
                         description: z.ZodOptional<z.ZodString>;
                         version: z.ZodDefault<z.ZodNumber>;
-                        payloadSchema: z.ZodRecord<z.ZodString, z.ZodType<JsonValue_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, unknown>>>;
+                        uriScheme: z.ZodString;
+                        relatedKeys: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                        payloadSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<JsonValue_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, unknown>>>>;
                     }, z.core.$strict>>>;
                     notificationRules: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -2954,6 +2969,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         url: z.ZodString;
                         auth: z.ZodOptional<z.ZodEnum<{
                             oauth: "oauth";
+                            "api-key": "api-key";
                             none: "none";
                         }>>;
                         authService: z.ZodOptional<z.ZodString>;
@@ -3060,6 +3076,8 @@ declare const KayPluginManifestV1: z.ZodObject<{
                                 "skills.read": "skills.read";
                                 "automations.run": "automations.run";
                                 "navigation.open-session": "navigation.open-session";
+                                "artifacts.read": "artifacts.read";
+                                "artifacts.preview": "artifacts.preview";
                                 "cost.read": "cost.read";
                                 "billing.read": "billing.read";
                                 "context.read": "context.read";
@@ -3072,6 +3090,16 @@ declare const KayPluginManifestV1: z.ZodObject<{
                                 "workspace.arrange": "workspace.arrange";
                             }>>>;
                         }, z.core.$strict>>;
+                        activityRail: z.ZodOptional<z.ZodObject<{
+                            section: z.ZodOptional<z.ZodEnum<{
+                                primary: "primary";
+                                plugins: "plugins";
+                            }>>;
+                            order: z.ZodOptional<z.ZodNumber>;
+                            icon: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                                svg: z.ZodString;
+                            }, z.core.$strict>]>>;
+                        }, z.core.$strict>>;
                     }, z.core.$strict>>>;
                     themes: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
@@ -3254,6 +3282,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3348,6 +3377,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -3442,6 +3472,7 @@ declare const KayPluginManifestV1: z.ZodObject<{
                     schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     operations: z.ZodArray<z.ZodEnum<{
                         status: "status";
+                        list: "list";
                         connect: "connect";
                         disconnect: "disconnect";
                         resolve: "resolve";
@@ -4277,9 +4308,10 @@ export declare interface OsascriptFailureAdvice {
 }
 
 /**
- * The activation options every osascript plugin's agent factory accepts
- * (`createAppleCalendarKayAgent(options)`), so the daemon's simulator roster sets each the same
- * way. Absent `simulator`, the plugin is exactly the shipped one.
+ * The activation options every osascript plugin's agent factory accepted, so the daemon's
+ * simulator roster set each the same way. Absent `simulator`, the plugin is exactly the shipped one.
+ *
+ * @deprecated See {@link OsascriptSimulatorOptions}.
  */
 export declare interface OsascriptKayAgentOptions {
     readonly simulator?: OsascriptSimulatorOptions;
@@ -4316,6 +4348,10 @@ export declare interface OsascriptRunner {
     /**
      * The runners a module's verbs use: the host's exactly when `simulator` is absent, or the
      * simulator's in its place, per dispatch, after the host's connection gate.
+     *
+     * @deprecated A Bonsai daemon substitutes the runner itself, so a module uses
+     * {@link requireExternalCli} and `ctx.auth?.externalCli` directly. Kept so a plugin built against
+     * an earlier SDK keeps compiling.
      */
     readonly dispatch: (simulator: OsascriptSimulatedRunner | undefined) => OsascriptDispatch;
     /**
@@ -4361,7 +4397,11 @@ export declare interface OsascriptRunnerOptions {
     readonly appNotRunning?: OsascriptFailureAdvice;
 }
 
-/** A plugin's simulator, as the runner sees it: the runner one dispatch uses in the host's place. */
+/**
+ * A simulated runner, as a module sees it: the runner one dispatch uses in the host's place. A
+ * Bonsai daemon that simulates an osascript plugin hands `runnerFor(ctx)` to the module as
+ * `ctx.auth.externalCli`; `@bonsai/uri-simulator-kit/osascript` builds one.
+ */
 export declare interface OsascriptSimulatedRunner {
     readonly runnerFor: (ctx: UriResolveContext) => UriExternalCliRunner;
 }
@@ -4370,6 +4410,10 @@ export declare interface OsascriptSimulatedRunner {
  * How a plugin is told to serve its module from its simulator instead of osascript: the one
  * option shape every osascript plugin's agent factory accepts as `simulator`. Only the daemon's
  * URI simulator roster sets it, for evals and dev; an ordinary install never does.
+ *
+ * @deprecated A Bonsai daemon now hands the module a simulated runner as `ctx.auth.externalCli`,
+ * so a plugin needs no simulator option; no Bonsai plugin sets this. Kept so a plugin built against
+ * an earlier SDK keeps compiling.
  */
 export declare interface OsascriptSimulatorOptions {
     /** The directory holding the simulator's world; the daemon's process config names it. */
@@ -5158,6 +5202,42 @@ export declare interface PluginDelegatedServiceEntry {
     readonly scheme: PluginDelegatedScheme;
 }
 
+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_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, 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_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, unknown>>>;
+}, z.core.$strict>;
+
+export declare type PluginEventPublishInput = z.infer<typeof PluginEventPublishInput>;
+
 /**
  * An external-CLI readiness scheme the plugin declares: a non-injectable marker for a
  * host-probed local binary (e.g. `osascript`, `gh`). Connecting runs `binary probeArgs`
@@ -6372,7 +6452,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>;
 }
 
 /**
@@ -6407,6 +6487,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
@@ -8598,6 +8684,14 @@ declare type TOmitDeferred<Type extends TSchema, Indexer extends TSchema> = (TDe
 
 declare type TOmitInstantiate<Context extends TProperties, State extends TState, Type extends TSchema, Indexer extends TSchema, InstantiatedType extends TSchema = TInstantiateType<Context, State, Type>, InstantiatedIndexer extends TSchema = TInstantiateType<Context, State, Indexer>> = TOmitAction<InstantiatedType, InstantiatedIndexer>;
 
+/**
+ * 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
@@ -8627,6 +8721,56 @@ export declare interface ToolAvailability {
     description: 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.
+ */
+export 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];
+
 /**
  * The neutral around-execution hook: return `next()`'s result (possibly transformed) to run the
  * real tool, or return a result without calling `next()` to substitute one — the tool then never