@yaklabs-ai/plugin-sdk 0.9.0 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.9.0"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.10.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/kay-app.d.ts

@@ -299,6 +299,93 @@ declare type ConstrainedSamplingConfig = {
     variants: GrammarVariants;
 };
 
+export declare interface CorpusResourceInvocation {
+    readonly eventId: string;
+    /** Envelope recording time, never a run/message/incident identifier. */
+    readonly at: string;
+    readonly kind: CorpusResourceKind;
+    readonly sessionId: string;
+    /** Falls back to sessionId for legacy events without a recorded root. */
+    readonly rootSessionId: string;
+    readonly name: string;
+    readonly sourceId?: string;
+    /** Absent on unresolved legacy rows; names/aliases are not a substitute. */
+    readonly resourceId?: string;
+    readonly version?: string;
+    readonly variantId?: string;
+    readonly rootProvenance: SessionProvenanceRecord;
+    /** Current index hints, not the session's historical context at invocation. */
+    readonly currentContext: {
+        readonly cwd: string;
+        readonly projectId?: string;
+    };
+}
+
+/** Exclusive keyset position; preserve timestamp precision when returning it. */
+export declare const CorpusResourceInvocationCursor: z.ZodObject<{
+    at: z.ZodISODateTime;
+    eventId: z.ZodString;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationCursor = z.infer<typeof CorpusResourceInvocationCursor>;
+
+export declare interface CorpusResourceInvocationExclusion {
+    readonly eventId: string;
+    readonly sessionId: string;
+    readonly rootSessionId: string;
+    readonly reason: "session-missing" | "root-missing" | "root-provenance-unverified" | "root-creator-filtered";
+}
+
+export declare type CorpusResourceInvocationPage = {
+    readonly state: "available";
+    readonly items: readonly CorpusResourceInvocation[];
+    /** Absent only when this recording-time window is exhausted. */
+    readonly next?: CorpusResourceInvocationCursor;
+    /** Telemetry import succeeded; exclusions still describe missing or filtered index facts. */
+    readonly coverage: {
+        readonly scanned: number;
+        readonly exclusions: readonly CorpusResourceInvocationExclusion[];
+    };
+} | {
+    readonly state: "unavailable";
+    readonly reason: "not-wired" | "telemetry-unavailable" | "telemetry-incomplete" | "index-unavailable" | "invalid-record";
+    readonly message: string;
+};
+
+/** Half-open recording-time window. Limits bound scanned rows, including exclusions. */
+export declare const CorpusResourceInvocationQuery: z.ZodObject<{
+    kind: z.ZodEnum<{
+        skill: "skill";
+        "context-file": "context-file";
+        "prompt-command": "prompt-command";
+    }>;
+    since: z.ZodISODateTime;
+    until: z.ZodISODateTime;
+    after: z.ZodOptional<z.ZodObject<{
+        at: z.ZodISODateTime;
+        eventId: z.ZodString;
+    }, z.core.$strict>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        plugin: "plugin";
+        trigger: "trigger";
+        daemon: "daemon";
+    }>>;
+}, z.core.$strict>;
+
+export declare type CorpusResourceInvocationQuery = z.infer<typeof CorpusResourceInvocationQuery>;
+
+/** Roster invocation facts, not evidence that a read completed successfully. */
+export declare const CorpusResourceKind: z.ZodEnum<{
+    skill: "skill";
+    "context-file": "context-file";
+    "prompt-command": "prompt-command";
+}>;
+
+export declare type CorpusResourceKind = z.infer<typeof CorpusResourceKind>;
+
 /**
  * The `signals` a host with no Jev lane or no signals store binds: `observe` never touches the
  * network, answers `invalid` for an input that breaks the recorded-name grammar exactly as a
@@ -1189,9 +1276,20 @@ export declare interface KayAppAutomationContext {
     readonly sessionId: string;
 }
 
-export declare type KayAppAutomationEffect = Extract<KayAppAutomationEffectInput, {
+export declare type KayAppAutomationEffect = {
+    /**
+     * STORED only: a binding created before the 2026-09-28 owner ruling (agents and plugins
+     * may not create `spawn-session` automations) can still carry this effect, so a read must
+     * still parse it. Absent from {@link KayAppAutomationEffectInput}, so no NEW binding can
+     * be minted with it.
+     */
     readonly kind: "spawn-session";
-}> | {
+    readonly prompt: string;
+    readonly cwd?: string;
+    readonly projectId?: string | null;
+    /** Resolve the spawned session's model by tier instead of the caller's default. */
+    readonly tier?: "small" | "medium" | "large" | "ultra";
+} | {
     /** As STORED: always a reference, never inline source. */
     readonly kind: "script";
     readonly ref: KayAppAutomationScriptRef;
@@ -1207,6 +1305,14 @@ export declare type KayAppAutomationEffect = Extract<KayAppAutomationEffectInput
     readonly prompt: string;
 };
 
+/**
+ * What a plugin may CREATE an automation with. `spawn-session` is deliberately absent: owner
+ * ruling (2026-09-28) forbids a plugin (or an agent) from minting a `spawn-session` binding —
+ * durable recurring agent work belongs to a plugin workflow (`app.workflows.define` +
+ * `ctx.runAgent`) or a direct `app.sessions.run`. A binding created before that ruling can still
+ * carry the effect and still reads and runs; see {@link KayAppAutomationEffect}, the STORED type
+ * this input narrows.
+ */
 export declare type KayAppAutomationEffectInput = {
     readonly kind: "deliver-turn";
     readonly prompt: string;
@@ -1220,13 +1326,6 @@ export declare type KayAppAutomationEffectInput = {
      */
     readonly source?: string;
     readonly initialState?: JsonValue_4;
-} | {
-    readonly kind: "spawn-session";
-    readonly prompt: string;
-    readonly cwd?: string;
-    readonly projectId?: string | null;
-    /** Resolve the spawned session's model by tier instead of the caller's default. */
-    readonly tier?: "small" | "medium" | "large" | "ultra";
 };
 
 /**
@@ -1495,6 +1594,8 @@ export declare type KayAppAutomationScriptRef = {
 
 /** A receipt-attributed skill candidate, with live status only for that exact revision. */
 export declare type KayAppAutomationSuggestionItem = {
+    /** Only literal 1 proves physical addressing; other historical values remain uninterpreted. */
+    readonly locatorVersion?: unknown;
     readonly sourceId: string;
     readonly skillName: string;
     readonly suggestionId: string;
@@ -1682,17 +1783,31 @@ export declare interface KayAppContextContributor {
  * Raw read access to every stored session's transcript. Always present on
  * {@link KayAppPluginApi}; each read is checked against the `corpus.read` claim, and refused
  * unless the user has granted it. Data is raw and un-redacted — the plugin filters to what it
- * needs. Both reads are async iterables so a corpus pass never loads the whole corpus into memory
- * at once (the bound is one session at a time).
+ * needs. Invocation queries are bounded pages. Transcript reads materialize a whole session
+ * before yielding; the iterable does not promise per-entry streaming or an allocation bound.
  */
 export declare interface KayAppCorpus {
+    /** Page invocation leads under the live grant; inspect exclusions even on available empty pages. */
+    listResourceInvocations(query: CorpusResourceInvocationQuery): Promise<CorpusResourceInvocationPage>;
     /** Enumerate every stored session, newest-first. */
     listSessions(): AsyncIterable<KayAppCorpusSession>;
     /**
-     * Stream one session's full entry log oldest→newest; an unknown id yields nothing. Treat the
+     * Yield one session's full entry log oldest→newest; an unknown id yields nothing. Treat the
      * entries as read-only: for a session the daemon holds in memory they are its live objects.
      */
     readEntries(sessionId: string): AsyncIterable<SessionTreeEntry>;
+    /**
+     * Read one bounded physical JSONL page. The host resolves `sessionId` to its authoritative
+     * indexed path and validates the opaque cursor before opening it. When `throughEntryId` is
+     * supplied, the cursor stops at that entry's transaction line; a V4 line may carry later
+     * entries, which are returned for the caller to filter and are replayed on the next page.
+     */
+    readEntryBatch?(sessionId: string, options?: {
+        readonly cursor?: JsonValue_4;
+        readonly throughEntryId?: string;
+        /** Host-only cancellation for the bounded physical read. */
+        readonly signal?: AbortSignal;
+    }): Promise<KayAppCorpusEntryBatch>;
     /**
      * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
      * sessions yield `undefined`.
@@ -1700,6 +1815,20 @@ export declare interface KayAppCorpus {
     readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
 }
 
+/** One bounded physical page from the host's incremental JSONL reader. */
+export declare interface KayAppCorpusEntryBatch {
+    readonly entries: readonly SessionTreeEntry[];
+    /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
+    readonly cursor: JsonValue_4;
+    /** Opaque cursor at the physical page start, for a partial logical chunk. */
+    readonly pageStartCursor?: JsonValue_4;
+    readonly mode: "replace" | "append";
+    readonly status: "complete" | "more" | "awaiting-append" | "record-too-large";
+    /** Present when a caller supplied `throughEntryId`. */
+    readonly anchorFound?: boolean;
+    readonly malformedRecords: number;
+}
+
 /** One stored session, as the granted corpus enumerates them. Keyed by its stable `sessionId`. */
 export declare interface KayAppCorpusSession {
     readonly sessionId: string;
@@ -1962,6 +2091,13 @@ export declare interface KayAppEndpoints {
     register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
 }
 
+/** A real human carrier projected into the source session's transcript. */
+export declare interface KayAppHumanMessageSessionEvent extends KayAppSessionEventBase {
+    readonly type: "human-message";
+    /** Exact prior persisted boundary captured by the host at projection time; `null` means empty history. */
+    readonly throughEntryId: string | null;
+}
+
 /**
  * A provider's nominated image model, resolved now: what a session on one of that
  * provider's text-only models spawns to read images. `resolved` absent = nothing
@@ -2584,17 +2720,16 @@ export declare type KayAppSessionCreator = SessionCreator;
 
 export declare type KayAppSessionDefiner = SessionDefiner;
 
-export declare type KayAppSessionEvent = KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent;
+export declare type KayAppSessionEvent = KayAppHumanMessageSessionEvent | KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent;
 
 declare interface KayAppSessionEventBase {
     readonly sessionId: string;
     /**
-     * The event's own anchor entry: the settled turn's own last entry, or the phase-shift
-     * observation's `observationEntryId`. A handler bounds its OWN corpus read using this id (via
-     * whatever packet-building helpers the plugin already owns); the door hands out no
-     * `readEntries()` closure, and re-validating what was read against the CURRENT branch — a
-     * rewind can race between publish and read — is the handler's own job, exactly as
-     * `resolveClosedPhase` already does today for the phase extractor.
+     * The event's own anchor entry: the projected human carrier, the settled turn's own last
+     * entry, or the phase-shift observation's `observationEntryId`. A handler bounds its OWN logical
+     * corpus interval using this id (via whatever packet-building helpers the plugin already owns);
+     * the door hands out no `readEntries()` closure, and re-validating what was read against the
+     * CURRENT branch — a rewind can race between publish and read — is the handler's own job.
      */
     readonly entryId: string;
     /** ISO-8601 publish time. */
@@ -2631,6 +2766,8 @@ export declare type KayAppSessionEventCause = {
          * substitute a run id resolved another way.
          */
         readonly runId?: string;
+        /** Exact prior persisted boundary for a projected human-message event; null means empty history. */
+        readonly throughEntryId?: string | null;
     };
     /**
      * Exact-match dedupe key. The host REFUSES a second run carrying the same key outright (a
@@ -2693,12 +2830,12 @@ export declare interface KayAppSessionEventsSubscribeOptions {
 }
 
 /**
- * A closed, extensible union: today's two root events a lane could fire on
- * (`turn-settled`) and react to (`phase-shift`), collapsed onto one subscribable set now that
- * there is no dispatcher chaining one lane's completion into another's `when`. Adding a third
- * type is additive, never breaking.
+ * A closed, extensible union: a projected human message, a settled turn, or an accepted
+ * phase-shift observation. They share one subscribable set now that there is no dispatcher
+ * chaining one job's completion into another's `when`. Adding a fourth type is additive, never
+ * breaking.
  */
-export declare type KayAppSessionEventType = "turn-settled" | "phase-shift";
+export declare type KayAppSessionEventType = "human-message" | "turn-settled" | "phase-shift";
 
 export declare type KayAppSessionIntent = SessionIntent;
 
@@ -4501,9 +4638,11 @@ declare const SessionCausedByEvent: z.ZodObject<{
         type: z.ZodEnum<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
+            "human-message": "human-message";
         }>;
         entryId: z.ZodString;
         runId: z.ZodOptional<z.ZodString>;
+        throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strict>>;
     dedupeKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -4697,9 +4836,11 @@ declare const SessionProvenanceRecord: z.ZodObject<{
             type: z.ZodEnum<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
+                "human-message": "human-message";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
+            throughEntryId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         }, z.core.$strict>>;
         dedupeKey: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",