@yaklabs-ai/plugin-sdk 0.13.0 → 0.13.2

package/dist/kay-app.d.ts

@@ -21,7 +21,7 @@ declare interface AccountIdentity {
     readonly displayName?: string;
     /** Absolute URL of the account's avatar. */
     readonly avatarUrl?: string;
-    /** Issuer-asserted beta-tester flag; only Kay's product-account service sets it. */
+    /** Issuer-asserted beta-tester flag; only Bonsai's product-account service sets it. */
     readonly betaTester?: boolean;
     readonly activeOrganizationId?: string;
     readonly organizationSelectionState?: "selected" | "unresolved";
@@ -29,7 +29,7 @@ declare interface AccountIdentity {
     /**
      * Provider-native session id claim (WorkOS's `sid`), needed to call the provider's own
      * session-revocation endpoint at sign-out (`POST /user_management/sessions/revoke`, not yet
-     * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Kay's WorkOS
+     * wired — see `docs/kay-account-auth.md`'s "Sign-out guarantee" section). Only Bonsai's WorkOS
      * product-account exchange/refresh sets it; every other provider leaves it absent.
      */
     readonly providerSessionId?: string;
@@ -431,6 +431,12 @@ export declare function createFallbackOnlyWithJev(): WithJev;
  */
 export declare function createUnavailableSkills(message: string): KayAppSkills;
 
+/**
+ * The `app.tools` a host that cannot describe tools binds: every call answers `not-available`, so
+ * a plugin's code path never depends on host composition.
+ */
+export declare function createUnavailableTools(): KayAppTools;
+
 declare interface CustomEntry extends EntryBase {
     type: "custom";
     customType: string;
@@ -762,7 +768,7 @@ export declare interface JevScoreQuestion {
  *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
  * ---
  *
- * The vocabulary is Kay's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
+ * The vocabulary is Bonsai's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
  * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
  * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
  * criterion is text, and the state is a JSON object.
@@ -904,7 +910,7 @@ declare interface KayAgentWhiteboardUpdateInput {
 }
 
 /**
- * The signed-in Kay account. Always present on {@link KayAppPluginApi}.
+ * The signed-in Bonsai account. Always present on {@link KayAppPluginApi}.
  *
  * Reading the profile is ungated: it exposes the signed-in user's own identity to a plugin they
  * explicitly enabled. The two stronger operations are separate claims, checked per call —
@@ -948,7 +954,7 @@ export declare interface KayAppAccount {
     assertResult?(): Promise<KayAppAccountAssertionResult>;
     /**
      * Change the user-editable part of the signed-in profile (today: the display name). PRESENT
-     * only with the `update` operation granted. Runs through Kay's own profile-update path — the
+     * only with the `update` operation granted. Runs through Bonsai's own profile-update path — the
      * same one Account settings uses — so the change reaches WorkOS, the local account snapshot,
      * Memory's account-owned person note, and every `subscribe` listener; later sessions see the
      * new name in their prompt. Rejects when signed out or when the backend refuses the value
@@ -991,7 +997,7 @@ export declare interface KayAppAccount {
  * issuer's own JWKS.
  *
  * It is **not audience-scoped**. A plugin holding it can present itself as the user to anything
- * that accepts a Kay product-account token, not only to the relying party it was fetched for.
+ * that accepts a Bonsai product-account token, not only to the relying party it was fetched for.
  * Treat it as live secret material: never log it, never put it in an event payload or an endpoint
  * response, never persist it. Read it, use it in the outbound request, drop it.
  *
@@ -1004,7 +1010,7 @@ export declare interface KayAppAccountAssertion {
     /**
      * The OIDC issuer that can verify `token`.
      *
-     * Travels with the assertion because Kay runs one product-account provider instance per release
+     * Travels with the assertion because Bonsai runs one product-account provider instance per release
      * channel (local-dev, Yak, production). A verifier that hardcodes the production issuer
      * silently rejects every other install.
      */
@@ -1052,8 +1058,8 @@ export declare type KayAppAccountAssertionResult = {
 };
 
 /**
- * Who is signed in to Kay. Metadata only — this carries no secret and cannot be presented to
- * anyone as proof. Derived from the Kay product-account record's stored identity.
+ * Who is signed in to Bonsai. Metadata only — this carries no secret and cannot be presented to
+ * anyone as proof. Derived from the Bonsai product-account record's stored identity.
  */
 export declare interface KayAppAccountProfile {
     /** The account's stable provider `sub`. Survives an email change; prefer it as a durable key. */
@@ -1062,7 +1068,7 @@ export declare interface KayAppAccountProfile {
     readonly displayName?: string;
     readonly avatarUrl?: string;
     /**
-     * Whether the account is a Kay beta tester, sourced from the Kay Cloud API's `GET /v1/me`
+     * Whether the account is a Bonsai beta tester, sourced from the Bonsai Cloud API's `GET /v1/me`
      * (authoritative). Absent means unknown, not "no" — a live read that could not run, or a
      * grant that predates the API becoming the source, are both indistinguishable here. A present
      * value is refreshed on a bounded interval, not only at sign-in; see
@@ -1127,6 +1133,10 @@ export declare interface KayAppAgentDefinition {
      * These rules outrank the human's standing settings-page preference (they seed a level above
      * `user`) and cannot be removed by the running session. They are re-read from the definition at
      * every session activation, so a rule the plugin stops declaring stops applying.
+     *
+     * They also bind every subagent such a session spawns with `agent_spawn`, and every subagent
+     * those spawn in turn. A subagent inherits only these rules (and {@link permissionsFallback}),
+     * not this definition's instructions or tool roster.
      */
     readonly permissions?: readonly PluginAgentDefinitionPermissionRule[];
     /**
@@ -1151,8 +1161,8 @@ export declare interface KayAppAgentDefinition {
 export declare interface KayAppAgentDefinitionConfig {
     /**
      * The definition's instructions: what this agent exists to do. Rendered as the
-     * agent-configuration trailer at the END of Kay's own prompt document, subordinate to
-     * everything above it. A definition never replaces Kay's prompt; it extends it.
+     * agent-configuration trailer at the END of Bonsai's own prompt document, subordinate to
+     * everything above it. A definition never replaces Bonsai's prompt; it extends it.
      */
     readonly instructions?: string;
     readonly activeToolNames?: readonly KayAppSessionRunHostToolName[];
@@ -1161,7 +1171,7 @@ export declare interface KayAppAgentDefinitionConfig {
     readonly thinkingLevel?: KayAppThinkingLevel;
     readonly cwd?: string;
     /**
-     * The definition's structured-output contract for a settled turn. Kay's own default agent
+     * The definition's structured-output contract for a settled turn. Bonsai's own default agent
      * carries its standing-recap contract through this field; a plugin-authored definition may
      * carry one too, with the same discipline: keep it optional, and use `whenToSubmit` to say
      * when it applies rather than making every turn terminate through it.
@@ -1493,7 +1503,7 @@ export declare type KayAppAutomationEffectInput = {
     /** The file this automation runs; every stored binding carries one. */
     readonly ref?: KayAppAutomationScriptRef;
     /**
-     * Inline source, at CREATE only: Kay saves it into the owning session's scripts folder
+     * Inline source, at CREATE only: Bonsai saves it into the owning session's scripts folder
      * and stores a reference to that file. Pass this OR `ref`, never both.
      */
     readonly source?: string;
@@ -1503,7 +1513,7 @@ export declare type KayAppAutomationEffectInput = {
 /**
  * One thing a run created OUTSIDE this machine — today a GitHub pull request
  * its session opened. A sibling of {@link KayAppAutomationArtifactItem}, not a
- * widening of it: an external resource has no revision, no Kay uri module, and
+ * widening of it: an external resource has no revision, no Bonsai uri module, and
  * nothing on this machine to re-read.
  *
  * `kind` is the run-detail wire's closed external-resource vocabulary and names
@@ -1685,12 +1695,12 @@ export declare type KayAppAutomationRunOutcome = {
 export declare interface KayAppAutomations {
     list(ctx: KayAppAutomationContext): Promise<readonly KayAppAutomationBinding[]>;
     /**
-     * Kay's own recurring work. NOT session-scoped, unlike {@link list}: these
+     * Bonsai's own recurring work. NOT session-scoped, unlike {@link list}: these
      * belong to the daemon, so every session sees the same set.
      */
     listManaged(ctx: KayAppAutomationContext): Promise<readonly KayAppManagedAutomation[]>;
     /**
-     * Run one of Kay's own automations now, without waiting for its schedule.
+     * Run one of Bonsai's own automations now, without waiting for its schedule.
      *
      * Separate from {@link runNow} because it addresses a different population:
      * `runNow` proves the caller owns the binding, and a managed automation has
@@ -1731,7 +1741,7 @@ export declare interface KayAppAutomations {
      * Switch one automation on or off.
      *
      * Reaches TWO populations, and the result says which one it answered about. A binding this
-     * session owns comes back as a full {@link KayAppAutomationBinding}. One of Kay's OWN
+     * session owns comes back as a full {@link KayAppAutomationBinding}. One of Bonsai's OWN
      * automations comes back as a {@link KayAppManagedAutomation} instead: its effect belongs to the
      * daemon and never crosses a plugin boundary, so there is no binding to hand back. That is the
      * whole reason this is a union rather than one shape - a caller reading `binding`
@@ -1820,9 +1830,9 @@ export declare type KayAppAutomationSuggestionItem = {
 });
 
 /**
- * Watch one Kay URI and fire only when what it reads back CHANGES. Carries no
+ * Watch one Bonsai URI and fire only when what it reads back CHANGES. Carries no
  * `sessionId`: unlike the fact-driven conditions, what it watches lives OUTSIDE
- * Kay — which is also why it outlives the session that created it.
+ * Bonsai — which is also why it outlives the session that created it.
  */
 export declare interface KayAppAutomationUriChangeCondition {
     readonly kind: "uri-change";
@@ -2052,6 +2062,14 @@ export declare interface KayAppCorpusEntryBatch {
 /** One stored session, as the granted corpus enumerates them. Keyed by its stable `sessionId`. */
 export declare interface KayAppCorpusSession {
     readonly sessionId: string;
+    /**
+     * Who the session is for, as stamped when it was created: a person's own session (`user`), a
+     * spawned subagent, or a session Bonsai runs with nobody watching (`system`, `followup`). It lets
+     * a reader skip sessions without opening their transcripts. Absent when the index does not know
+     * it (a session older than origin stamping, or a row not yet rebuilt from its transcript): that
+     * is unknown, not `user`.
+     */
+    readonly origin?: KayAppSessionOrigin | undefined;
 }
 
 /** Cheap identity for the current contents of one stored session transcript. */
@@ -2263,7 +2281,7 @@ export declare interface KayAppDynamicContextContribution {
 }
 
 /**
- * One delivery pass's request. For modern Kay sends, `texts` contains one
+ * One delivery pass's request. For modern Bonsai sends, `texts` contains one
  * source-ordered human-input projection with inline paste nodes expanded to
  * their exact bodies. Older paste-aware clients contribute their exact inline
  * paste bodies. UI-generated labels such as `[Pasted 21 lines]` never appear.
@@ -2280,7 +2298,7 @@ export declare interface KayAppDynamicContextRequest {
     readonly search: (opts?: KayAppDynamicContextSearchOptions) => Promise<readonly KayAppDynamicContextSearchHit[]>;
 }
 
-/** One indexed reference from Kay's shared knowledge — routes plus revision identity, never answers. */
+/** One indexed reference from Bonsai's shared knowledge — routes plus revision identity, never answers. */
 export declare interface KayAppDynamicContextSearchHit {
     readonly uri: string;
     readonly score: number;
@@ -2310,7 +2328,7 @@ export declare interface KayAppDynamicContextSearchOptions {
 
 /**
  * The app-wide endpoint bus. A plugin registers named handlers a consuming surface can invoke; the
- * host routes invocations (e.g. Kay Desktop forwards the renderer's frame-gated call to the daemon,
+ * host routes invocations (e.g. Bonsai Desktop forwards the renderer's frame-gated call to the daemon,
  * where the endpoint is single-homed). The corpus is NEVER reachable here — only what the plugin
  * explicitly exposes. Both `payload` and the handler's return ride strict JSON on the wire.
  */
@@ -2383,7 +2401,7 @@ export declare interface KayAppLifecycle {
  * each write or run is checked against `automations.write` / `automations.run`.
  */
 /**
- * One of Kay's OWN recurring automations — a bundled plugin's nightly
+ * One of Bonsai's OWN recurring automations — a bundled plugin's nightly
  * workflow, the knowledge sweep — as a plugin may see it.
  *
  * A narrow projection rather than a binding: a managed automation's effect
@@ -2495,7 +2513,7 @@ export declare interface KayAppModelFeatures {
     readonly maxOutputTokens?: number;
 }
 
-/** The plugin-safe projection of one model in Kay's live model catalog. */
+/** The plugin-safe projection of one model in Bonsai's live model catalog. */
 export declare interface KayAppModelInfo {
     readonly modelReference: string;
     readonly provider: string;
@@ -2521,7 +2539,7 @@ export declare type KayAppModelModality = "text" | "image" | "audio" | "video" |
 export declare interface KayAppModels {
     /** Returns the current projection; an empty catalog is an empty array. */
     list(): Promise<readonly KayAppModelInfo[]>;
-    /** Present when the host resolves image-model nominations (every Kay daemon does). */
+    /** Present when the host resolves image-model nominations (every Bonsai daemon does). */
     resolveImageModel?(provider: string): Promise<KayAppImageModelInfo>;
     /**
      * Returns the four product model tiers, each with its live point-in-time resolution
@@ -2562,7 +2580,7 @@ export declare type KayAppModelSelection = {
     readonly provider?: string | undefined;
 };
 
-/** Kay's canonical task-difficulty tier vocabulary at the plugin boundary. */
+/** Bonsai's canonical task-difficulty tier vocabulary at the plugin boundary. */
 export declare type KayAppModelTierId = "small" | "medium" | "large" | "ultra";
 
 /**
@@ -2609,7 +2627,7 @@ export declare interface KayAppPaths {
      */
     readonly sessionsRoot?: string;
     /**
-     * Absolute path to Kay's local telemetry directory. The live telemetry lane itself is a
+     * Absolute path to Bonsai's local telemetry directory. The live telemetry lane itself is a
      * Postgres table (`telemetry.usage_events`), not anything under this path; it is never a
      * PostHog credential or a remote-export queue. This directory used to hold the retired
      * file-based store's JSONL journals and compacted Parquet, but those are moved aside once,
@@ -2619,7 +2637,7 @@ export declare interface KayAppPaths {
      */
     readonly telemetryRoot?: string;
     /**
-     * Absolute path to Kay's observability log directory. The two JSONL event lanes live here: the
+     * Absolute path to Bonsai's observability log directory. The two JSONL event lanes live here: the
      * Desktop main process appends `kay-<YYYY-MM-DD>.jsonl` (fatal-startup records append into that
      * same lane) and the daemon appends `kay-runtime-<YYYY-MM-DD>.jsonl` — read BOTH lanes, or you
      * are reading half the system. Lane files rotate daily, gain a `.N` suffix past 50 MB, and are
@@ -2683,7 +2701,7 @@ export declare interface KayAppPluginApi {
     /** Register app-lifetime cleanup for plugin-owned processes, sockets, watchers, or timers. */
     readonly lifecycle: KayAppLifecycle;
     /**
-     * Manifest-declared app-data sources. Present whenever the host runs an app-data lane (every Kay
+     * Manifest-declared app-data sources. Present whenever the host runs an app-data lane (every Bonsai
      * daemon does); absence means THIS host composed none, never that a grant is missing. Each
      * registration is checked against `app-data.register {source}` for the declared
      * `contributes.dataSources` localId it names.
@@ -2703,7 +2721,7 @@ export declare interface KayAppPluginApi {
      */
     readonly corpus: KayAppCorpus;
     /**
-     * The signed-in Kay product account. Present whenever the host runs an account service; absence
+     * The signed-in Bonsai product account. Present whenever the host runs an account service; absence
      * means this host composed none, never that a grant is missing. Reading identity is ungated; the
      * two stronger operations are checked per call against `account.assert` and `account.update`.
      */
@@ -2851,6 +2869,14 @@ export declare interface KayAppPluginApi {
      * present, like {@link signals}.
      */
     readonly skills: KayAppSkills;
+    /**
+     * What a live session's tools and addresses say to the agent, where each comes from, and whether
+     * each is one of Bonsai's own. Each call is checked against `tools.describe`; a refused grant or
+     * a session that is not live resolves to `{ status: "unavailable" }`, never a rejection, while
+     * the plugin is enabled. After it is disabled, a kept handle's methods throw synchronously.
+     * Always present, like {@link skills}.
+     */
+    readonly tools: KayAppTools;
     /** The app-wide endpoint bus (register handlers a consuming surface invokes). */
     readonly endpoints: KayAppEndpoints;
     /** Publish one event declared by this plugin's `kay.app` manifest target. */
@@ -3409,6 +3435,14 @@ export declare interface KayAppSessions {
         /** Omit to inherit the opener; null explicitly selects no project. */
         readonly projectId?: string | null;
         readonly title?: string | undefined;
+        /**
+         * The new session's model, as a tier word (`small`, `medium`, `large`, `ultra`): the daemon
+         * picks the concrete model through the same tier resolution every other tier choice takes.
+         * Absent, the person's own selection applies, so a session a plugin opens on its own account
+         * runs on whatever they happen to be using, Ultra included. Work that does not need a strong
+         * model names a tier. A tier only: an exact model pin is not offered here.
+         */
+        readonly tier?: KayAppModelTierId | undefined;
         /**
          * The session asking for this one, so the daemon can record which session opened it.
          * Pass the calling tool's own `ctx.sessionId` and nothing else: the daemon vets the id
@@ -3447,7 +3481,7 @@ export declare interface KayAppSessions {
         readonly kind: "unavailable";
     }>;
     /**
-     * Run one hidden headless system session through Kay's harness and resolve
+     * Run one hidden headless system session through Bonsai's harness and resolve
      * with its final output — the sole sanctioned way for a `kay.app` plugin to
      * spend model tokens outside a session-event handler. Checked per call against
      * the `sessions.run` claim. A plugin may request a model/tier and supply
@@ -3508,6 +3542,10 @@ export declare interface KayAppSignal {
         readonly pluginId: string;
     };
     readonly source: KayAppSignalSource;
+    /** What the signal is about, when its recorder named a subject. */
+    readonly subject?: KayAppSignalSubject;
+    /** The id of the upstream signal this one was chained after, while that row exists. */
+    readonly upstreamId?: number;
     readonly recordedAtMs: number;
     /** Keyed by question name, full probability distributions included. */
     readonly answers: Readonly<Record<string, KayAppSignalAnswer>>;
@@ -3567,12 +3605,20 @@ export declare interface KayAppSignalNoulAnswer {
  *
  * A repeat call over the same (plugin, detector, version, session, entry, input digest) returns
  * the ALREADY-STORED row with `deduplicated: true` and never calls Jev again: replay is free.
+ * A call with `reuse` that finds a recent row for the same subject key returns that row with
+ * `deduplicated: true` and `reused: true`; its `source` is where the row was computed.
  */
 export declare interface KayAppSignalObservation {
     readonly id?: number | undefined;
     readonly status: "classified" | "unavailable" | "invalid";
     readonly detector: KayAppSignalsDetectorRef;
     readonly source: KayAppSignalSource;
+    /** The row's subject, when it was recorded with one. */
+    readonly subject?: KayAppSignalSubject | undefined;
+    /** The row's upstream link: the id of the row it was chained after. */
+    readonly upstreamId?: number | undefined;
+    /** True when the answer is a stored row found through `reuse`, not this call's own. */
+    readonly reused?: boolean | undefined;
     readonly answers?: Record<string, unknown> | undefined;
     readonly model?: string | undefined;
     readonly usage?: {
@@ -3605,6 +3651,18 @@ export declare interface KayAppSignalPage {
     readonly nextCursor?: string;
 }
 
+/**
+ * Reuse a stored answer for the same subject instead of asking Jev again. Before any Jev call
+ * the host looks for the newest row this plugin recorded with the same detector, version,
+ * subject key and input digest, recorded at most `maxAgeMs` ago, in ANY session. When one
+ * exists, that row is the answer: no Jev call and no new row. The returned observation keeps the
+ * row's own source (where it was computed), with `reused: true`.
+ */
+declare interface KayAppSignalReuse {
+    /** How old a stored answer may be, in ms: a whole number from 1 to {@link SIGNAL_TIME_MAX_MS}. */
+    readonly maxAgeMs: number;
+}
+
 /**
  * One question of a stored rubric, as the recording plugin wrote it. Rubrics recorded before
  * SDK 0.12.0 use TypeSafe's vocabulary (`noul` for yes/no, and instructions or criteria that
@@ -3733,6 +3791,12 @@ export declare interface KayAppSignalsDetectorRef extends KayAppSignalsDetectorI
 export declare interface KayAppSignalsObserveInput {
     readonly detector: KayAppSignalsDetectorInput;
     readonly source: KayAppSignalSource;
+    /** What the signal is about. Stored on the row; not part of the dedupe key or the input digest. */
+    readonly subject?: KayAppSignalSubject;
+    /** The upstream row this observation is chained after. Stored on the row as its upstream link. */
+    readonly after?: KayAppSignalUpstreamLink;
+    /** Reuse a recent stored answer for the same subject key. Needs `subject.key`. */
+    readonly reuse?: KayAppSignalReuse;
     /**
      * The exact state to send, already shaped by the caller (a turn packet, a window of messages,
      * or anything else). NOT stored: the row keeps its digest, and a reader re-derives it from the
@@ -3830,6 +3894,34 @@ export declare interface KayAppSignalsSessionQuery {
     readonly limit?: number;
 }
 
+/**
+ * What a signal is about, named by the recording plugin. The host stores both values and never
+ * interprets them. A signal recorded without a subject has none; every reader treats it as before.
+ */
+declare interface KayAppSignalSubject {
+    /**
+     * The kind of thing observed, e.g. `turn`: a lowercase slug of at most 64 characters, in the
+     * same grammar as a detector id.
+     */
+    readonly kind: string;
+    /**
+     * The subject's identity ACROSS sessions, when it has one (two sessions can observe the same
+     * subject). Required for {@link KayAppSignalsObserveInput.reuse}. 1 to 256 characters with no
+     * whitespace, `/`, `?`, `#`, or control or invisible character.
+     */
+    readonly key?: string;
+}
+
+/**
+ * The upstream signal a chained observation ran after: the stored row whose answers the caller
+ * found passing. The host checks that the row exists and was recorded by the same plugin, and
+ * stores the link on the new row; it never re-judges the caller's pass condition.
+ */
+declare interface KayAppSignalUpstreamLink {
+    /** The upstream row's `id`: a positive whole number. */
+    readonly observationId: number;
+}
+
 /** One managed skill, as the skill catalog admits it. */
 export declare interface KayAppSkill {
     /** Canonical id, `<canonical source id>/<name>`. Equal to a skill invocation's `resourceId`. */
@@ -3846,7 +3938,7 @@ export declare interface KayAppSkill {
 export declare interface KayAppSkillDetail extends KayAppSkill {
     readonly versioning: KayAppSkillVersioning;
     /**
-     * The version a session loading the skill now receives, as `git-tree:<oid>`. Absent when Kay
+     * The version a session loading the skill now receives, as `git-tree:<oid>`. Absent when Bonsai
      * keeps no history of the skill (`unversioned`), cannot read it, or the skill's files hold
      * bytes no revision has recorded (`uncommitted`).
      */
@@ -3886,7 +3978,7 @@ export declare interface KayAppSkillNotFound {
     readonly message: string;
 }
 
-/** Who made a revision, as Kay recorded it when the revision was made. Absent fields are unknown. */
+/** Who made a revision, as Bonsai recorded it when the revision was made. Absent fields are unknown. */
 export declare interface KayAppSkillProvenance {
     /** The session whose work the revision records. */
     readonly sessionId?: string;
@@ -4002,9 +4094,9 @@ export declare interface KayAppSkillsUnavailable {
 }
 
 /**
- * Whether Kay keeps a history for the skill, and how its local copy relates to its source.
- * `unversioned`: the skill's files are the user's own, and Kay keeps no history of them.
- * `unavailable`: Kay does keep one and cannot read it right now.
+ * Whether Bonsai keeps a history for the skill, and how its local copy relates to its source.
+ * `unversioned`: the skill's files are the user's own, and Bonsai keeps no history of them.
+ * `unavailable`: Bonsai does keep one and cannot read it right now.
  */
 export declare type KayAppSkillVersioning = "pristine" | "customized" | "update-available" | "diverged" | "unversioned" | "unavailable";
 
@@ -4020,7 +4112,7 @@ export declare interface KayAppStorage {
     readonly dataDir?: KayAppDataDirStorage;
 }
 
-/** Kay's reasoning-effort ladder, in ascending order. */
+/** Bonsai's reasoning-effort ladder, in ascending order. */
 export declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 /**
@@ -4124,6 +4216,21 @@ export declare type KayAppToolDefinition<TParams extends ToolParametersWire = To
     execute(toolCallId: string, params: ToolExecutionAwareParams<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: KayAppToolContext): Promise<AgentToolResult<TDetails>>;
 };
 
+export declare interface KayAppToolDescription {
+    readonly ref: KayAppToolRef;
+    /** `false`: no such tool is registered, or no module owns that address, in this session. */
+    readonly found: boolean;
+    /**
+     * For a tool, its own registered description. For an address, its help rendered as `help <uri>`
+     * renders it for the agent; for `mcp://<server>`, that is the server's tool list in the server's
+     * own words.
+     */
+    readonly description?: string;
+    readonly origin?: KayAppToolOrigin;
+    /** Whether this is one of Bonsai's own tools or addresses. `false` when not found. */
+    readonly ownedByBonsai: boolean;
+}
+
 /**
  * The fine-grained, app-wide per-tool event stream (every session's tool executions). Carries the
  * redaction caveat: raw tool args/results are OFF in packaged builds, so a handler must treat
@@ -4136,9 +4243,23 @@ export declare interface KayAppToolEvents {
     subscribe(handler: (event: unknown) => void): () => void;
 }
 
+/** Where a described tool or address comes from. */
+export declare type KayAppToolOrigin = 
+/** The agent kernel's own (`bash`, `read`, `help`, `skill://`). */
+    {
+    readonly kind: "core";
+}
+/** Bonsai's host, outside any plugin (`task_status`, `config://`). */
+| {
+    readonly kind: "host";
+} | {
+    readonly kind: "plugin";
+    readonly pluginId: string;
+};
+
 /**
  * `app.permissions` — the plugin-facing seam through which a `kay.app` target advertises the
- * permission rows for tools it gates DYNAMICALLY, so they show in Kay's permission ledger with
+ * permission rows for tools it gates DYNAMICALLY, so they show in Bonsai's permission ledger with
  * the same allow / ask / never control every statically declared tool row has.
  *
  * A tool a plugin registers at activation (`registerTool`) is already a row: the host derives it
@@ -4186,6 +4307,52 @@ export declare interface KayAppToolPermissionSource {
     readonly list: () => readonly KayAppToolPermissionDeclaration[] | Promise<readonly KayAppToolPermissionDeclaration[]>;
 }
 
+/**
+ * The plugin-facing `kay.app` tools contract: for the tools and addresses a live session can use,
+ * the text the agent sees for each, where each comes from, and whether each is one of Bonsai's own.
+ *
+ * Every call is checked against the `tools.describe` claim at the call, so a grant or revocation
+ * takes effect on the next one. Like `app.skills`, the member is ALWAYS present and no call rejects
+ * while the plugin is enabled: a refused grant or a session that is not live resolves to
+ * `{ status: "unavailable" }`. After the plugin is disabled, a kept handle's methods throw
+ * synchronously.
+ *
+ * `ownedByBonsai` is a fact declared where each surface is defined (a bundled plugin's manifest, or
+ * the host's own registration), never a list kept by the host. What a plugin does with it is the
+ * plugin's call.
+ */
+/** A tool or an address to describe. */
+export declare type KayAppToolRef = 
+/** A registered tool by name, e.g. `bash`, `read`, `mcp`, `submit_final`. */
+    {
+    readonly kind: "tool";
+    readonly name: string;
+}
+/** A URI address whose `help` is wanted, e.g. `gmail://` or `mcp://linear`. */
+| {
+    readonly kind: "address";
+    readonly uri: string;
+};
+
+/** `app.tools`: what a live session's tools and addresses say, each call checked against `tools.describe`. */
+export declare interface KayAppTools {
+    describe(sessionId: string, refs: readonly KayAppToolRef[]): Promise<KayAppToolsDescribeResult>;
+}
+
+/**
+ * `not-granted`: the user has not granted `tools.describe`. `no-session`: the session is not live
+ * on this host (only live sessions are described). `not-available`: this host cannot describe
+ * tools.
+ */
+export declare type KayAppToolsDescribeResult = {
+    readonly status: "ok";
+    /** One per ref, in the order of the refs. */
+    readonly tools: readonly KayAppToolDescription[];
+} | {
+    readonly status: "unavailable";
+    readonly reason: "not-granted" | "no-session" | "not-available";
+};
+
 /** An eligible settled turn — the generic door's root event. */
 export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEventBase {
     readonly type: "turn-settled";
@@ -4203,7 +4370,7 @@ export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEven
      */
     readonly runId?: string;
     /**
-     * The SCRIPTED experience that minted this session, if one did — Kay's first-run
+     * The SCRIPTED experience that minted this session, if one did — Bonsai's first-run
      * conversation, the overnight handoff. Absent for an ordinary session, and absent whenever
      * the session was created by anything other than a person, so its presence means exactly
      * "a person's session, running a scripted arc".
@@ -4414,8 +4581,8 @@ export declare interface KayAppWhiteboardTypes {
  *
  * ## Your body can run more than once, and that is the point
  *
- * A workflow body is durable: if Kay is killed mid-run (a crash, a quit, a machine that went to
- * sleep), the run is picked up again when Kay comes back. It is picked up by RE-EXECUTING your
+ * A workflow body is durable: if Bonsai is killed mid-run (a crash, a quit, a machine that went to
+ * sleep), the run is picked up again when Bonsai comes back. It is picked up by RE-EXECUTING your
  * callback from the top — not by resuming it where it stopped, which JavaScript cannot do.
  *
  * What makes that safe is that the work you did inside `runStep` and `runAgent` is not done
@@ -4454,11 +4621,11 @@ export declare interface KayAppWorkflowContext {
     /**
      * Record a step's result for replay.
      *
-     * Once the result commits, recovery returns it without running the callback again. If Kay
+     * Once the result commits, recovery returns it without running the callback again. If Bonsai
      * stops before that commit, the callback can run again. Use idempotency keys for external
      * effects whose duplicates would matter; recording a step cannot transact with an email send.
      *
-     * What you return must be plain data Kay can store (JSON): objects, arrays, strings, numbers,
+     * What you return must be plain data Bonsai can store (JSON): objects, arrays, strings, numbers,
      * booleans, null. Not a class instance, a stream, a function or a handle.
      *
      * `name` labels the step wherever runs are inspected. Give it one; a body whose steps are all
@@ -4470,7 +4637,7 @@ export declare interface KayAppWorkflowContext {
     /**
      * Wait, durably.
      *
-     * Unlike `setTimeout`, this survives Kay being restarted: a body that sleeps for an hour and is
+     * Unlike `setTimeout`, this survives Bonsai being restarted: a body that sleeps for an hour and is
      * killed after ten minutes wakes at the original deadline rather than starting the hour again,
      * and it does not hold a process open while it waits.
      */
@@ -4483,14 +4650,14 @@ export declare interface KayAppWorkflowContext {
      * callback settles and every child you admitted has drained. Admission closes the moment your
      * callback settles, so a call made after that is refused rather than orphaned.
      *
-     * With an input `key`, Kay records the session before its first turn. Recovery sends a
+     * With an input `key`, Bonsai records the session before its first turn. Recovery sends a
      * continuation to that same persisted session; a new session is created only if its transcript
      * is gone. Settled memo results return directly. A crash after a turn settles but before its
      * memo commits can cause one extra continuation turn in the same session.
      *
      * A keyed child whose turn fails for a transient reason (`network`, `stream_interrupted`,
      * `overloaded`, `rate_limit`, `server_error`, or `timeout` when you declared no `timeoutMs`) is
-     * continued the same way: Kay waits, waits for the network when it can probe it, and sends a
+     * continued the same way: Bonsai waits, waits for the network when it can probe it, and sends a
      * continuation to the same session, up to six times and for at most 20 hours after the first
      * failure. A continuation the host refuses counts as one attempt and keeps the failure. Only
      * the final outcome returns and is memoized. Unkeyed children and every other failure return at
@@ -5907,6 +6074,14 @@ export declare interface ToolDefinition<TParams extends ToolParametersWire = Too
      * explicit Stop.
      */
     durationClass?: "fast" | "long";
+    /**
+     * Set only for a tool whose rerun with the same arguments is harmless, such
+     * as one keyed on its own call: after a crash cuts a call off, a pi-durable
+     * session may rerun it with its recorded arguments (without `before_tool`)
+     * instead of ending it as an interrupted error. Absent: never rerun. Ignored
+     * on pi 0.99.1.
+     */
+    replaySafe?: true;
     /**
      * Optional capability⇄scheme binding. When present this tool is auth-gated: discoverable when
      * unauthed, callable once the binding is satisfied. The SDK's {@link withResolvedAuth}
@@ -5990,9 +6165,9 @@ export declare type ToolParametersWire = unknown;
  *
  * The host is trusted to supply honest values; a declared `kind` of `read` moves a call below
  * the protected-path hard-deny (which only fires for non-read kinds), so a tool that could
- * touch protected config must NOT declare `read`. Kay's embedded-experience tools never touch
+ * touch protected config must NOT declare `read`. Bonsai's embedded-experience tools never touch
  * `configDir`, so this is safe for them. `read` is also what every capability surface reports as
- * "read-only" (Kay's Permissions page groups and defaults on it), so it is a claim about what the
+ * "read-only" (Bonsai's Permissions page groups and defaults on it), so it is a claim about what the
  * tool DOES — never a way to buy silence. A tool that should raise no ask on its own account
  * declares {@link ToolPermissionHint.quiet} and keeps its honest `kind`.
  */
@@ -6033,7 +6208,7 @@ export declare interface ToolPermissionHint {
      * because the same tool can read on one input and execute on another, which a static `kind`
      * cannot express.
      *
-     * Exemplar — Kay's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
+     * Exemplar — Bonsai's `mcp` proxy tool, one tool spanning every server: `search`/`describe` derive
      * `{ kind: "read" }` (metadata lookups), while `call` derives
      * `{ kind: "execute", ruleKey: "mcp:<server>::<tool>", scheme: "<server>" }`, so a
      * `{ scheme: "<server>" }` rule gates a whole server and a `{ ruleKey: "mcp:<server>::<tool>" }`
@@ -6074,7 +6249,7 @@ export declare interface ToolPermissionHint {
      * really had — not that the result is always stricter than the target's. How much gate is left
      * on such a call is exactly how much the CARRIER carries: an `execute` carrier is stricter than
      * a `read` target and equal to a `mutate`/`destructive` one outside allow mode, while a
-     * {@link quiet} carrier (Kay's own `call_tool`) contributes no mode default at all, so the
+     * {@link quiet} carrier (Bonsai's own `call_tool`) contributes no mode default at all, so the
      * fallback leaves nothing but the carrier's rules and the protected-path deny — and the carrier
      * names no path, so that deny has nothing to fire on. This is why a carrier must refuse a target
      * that is itself a carrier: no chain long or circular enough to reach the fallback can be built,
@@ -6098,7 +6273,7 @@ export declare interface ToolPermissionHint {
      * whose only effect is invoking the target the gate is already classifying beside it: the
      * target's kind, rules, resources and the protected-path deny all still decide, so a proxied
      * call is gated exactly like the direct one — no more, and no ask the direct call would never
-     * have raised. Kay's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
+     * have raised. Bonsai's `call_tool` declares `{ kind: "execute", quiet: true }` (owner ruling,
      * 2026-08-18): honest about everything it can reach, silent on its own account.
      *
      * Quiet is not ungated, but it IS nearly all the gate a lone carrier has. On a call that
@@ -6341,6 +6516,12 @@ declare interface UriHelp {
     readonly templates?: readonly UriTemplate[];
     readonly examples?: readonly UriExample[];
     readonly notes?: readonly string[];
+    /**
+     * Set when this help, for the address it was asked about, carries text a third party wrote and
+     * the module relays as it received it (an MCP server's own tool names and descriptions), rather
+     * than text the module's author wrote. Absent: the module's own text.
+     */
+    readonly thirdPartyContent?: true;
 }
 
 declare interface UriHintTriggers {
@@ -6452,8 +6633,9 @@ export declare interface UriModule {
     readonly description?: string;
     readonly agentHint?: UriAgentHint;
     /**
-     * Route-aware permission facts for operations whose effect is stricter than
-     * the generic URI verb implies. Scheme and resource scoping remain
+     * Route-aware permission facts for write/edit/delete routes whose effect is
+     * stricter than the generic URI verb implies (read verbs stay `read`; see
+     * {@link UriOperationPermissionPolicy}). Scheme and resource scoping remain
      * kernel-derived from the canonical URI.
      */
     readonly permission?: UriOperationPermissionPolicy;
@@ -6563,8 +6745,13 @@ export declare interface UriModule {
      * conversion stage, or an already-rendered `string` for synthesizing/text modules
      * (finalize passes those through its identity path). The single transport shape;
      * {@link finalize} (stage 2) turns it into model-facing content.
+     *
+     * Observes only, like `help`, `list` and `search` (the protocol contract in `@herd/uri`):
+     * repeating the call must be harmless, because the kernel reruns one a crash cut off without
+     * asking again.
      */
     read(input: string, ctx: UriResolveContext): Promise<RawResource>;
+    /** Observes only; see {@link read}. */
     help?(input: string, ctx: UriResolveContext): Promise<UriHelp>;
     write?(input: string, content: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult | void>;
     /** Structured write with host-resolved resources delivered beside the model-authored content. */
@@ -6581,7 +6768,9 @@ export declare interface UriModule {
      */
     writeBytes?(input: string, bytes: Uint8Array, source: UriSourceDescriptor, ctx: UriResolveContext): Promise<UriMutationResult | void>;
     edit?(input: string, patch: UriPayload, ctx: UriResolveContext): Promise<UriMutationResult>;
+    /** Observes only; see {@link read}. */
     list?(input: string, params: UriListParams, ctx: UriResolveContext): Promise<UriListResult>;
+    /** Observes only; see {@link read}. */
     search?(input: string, params: UriSearchParams, ctx: UriResolveContext): Promise<UriSearchResult>;
     delete?(input: string, ctx: UriResolveContext): Promise<UriMutationResult>;
     toMarkdown?(input: UriMarkdownRenderInput, ctx: UriResolveContext): string | undefined;
@@ -6679,7 +6868,9 @@ declare interface UriOperationPermissionClassification {
     /**
      * The operation's real effect. The permission classifier only accepts a
      * classification at least as restrictive as the URI verb's built-in
-     * classification.
+     * classification, and `read` for `help`/`read`/`list`/`search` (those
+     * verbs only observe; see {@link UriModule.read}). Anything else fails the
+     * preflight closed.
      */
     readonly kind: ToolActionKind;
     /** Optional route-specific rule key (for example, `terminal:input`). */
@@ -6689,8 +6880,9 @@ declare interface UriOperationPermissionClassification {
 declare interface UriOperationPermissionPolicy {
     /**
      * Classify one canonical route without I/O or caller/session state. Throwing,
-     * returning an invalid value, or weakening the verb's built-in classification
-     * fails the permission preflight closed.
+     * returning an invalid value, weakening the verb's built-in classification, or
+     * moving a `help`/`read`/`list`/`search` route off `read` fails the permission
+     * preflight closed.
      */
     classifyOperation(request: {
         readonly operation: UriOperation;
@@ -6895,7 +7087,7 @@ declare interface UriResolveContext_2 {
      * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller — so a module
      * writing to a store it owns can record the actor without the agent being able to choose one.
      *
-     * Free text minted by the host's own runtime (Kay's form is `user`, `subagent`,
+     * Free text minted by the host's own runtime (Bonsai's form is `user`, `subagent`,
      * `system/<surface>`, `followup/<surface>`) rather than a closed union: the surface half is the
      * host's vocabulary, and a second enumeration of it here would drift from the first.
      *