@yaklabs-ai/plugin-sdk 0.10.0 → 0.11.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.10.0"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.11.0"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

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

package/dist/disclosure.js

@@ -272,6 +272,9 @@ var URI_HINT_FIELD_LIMITS = {
   triggerItem: LIST_ITEM_LIMIT_CHARS
 };
 
+// packages/herd-agent/dist/core/tools/produced-resources.js
+var DECLARATIONS = Symbol.for("herd.producedResources.declarations");
+
 // packages/plugin-sdk/dist/disclosure/disclosure-conformance.js
 var PLUGIN_DISCLOSURE_RULES = [
   // (a) the agentHint a module must ship to be discoverable at all

package/dist/kay-agent-testing.d.ts

@@ -1498,6 +1498,58 @@ declare interface PluginServiceDescriptor {
     readonly capabilities: readonly PluginServiceCapability[];
 }
 
+/**
+ * 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.
+ */
+export declare type ProducedResourceDeclarationsRead = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "malformed";
+} | {
+    readonly kind: "declared";
+    readonly resources: readonly ProducedResourceDeclaration[];
+};
+
+/**
+ * What the automation run reader will see for one tool result's produced-resource declarations:
+ * the result's details recorded by the same host step a session applies before persisting it,
+ * then read through the `@herd/uri` contract. `declared` lists what `declareProducedResources`
+ * attached, in order; `absent` means the result claims nothing, including a result whose own
+ * details set the reserved key by hand, which the host drops.
+ *
+ * Stricter than the host on purpose: a declaration the contract refuses does not fail the tool
+ * call in a session (its effect already happened; the run reports a gap instead), so a test is
+ * where its author finds out.
+ *
+ * ```ts
+ * const result = await invokeToolForTest(createPageTool, { title: "Plan" });
+ * expect(producedResourcesForTest(result)).toEqual({
+ *   kind: "declared",
+ *   resources: [{ uri: "notion://pages/abc123", action: "created" }],
+ * });
+ * ```
+ *
+ * @throws TypeError when the result declares something the contract refuses, naming the claim.
+ */
+export declare function producedResourcesForTest(result: AgentToolResult<unknown>): Exclude<ProducedResourceDeclarationsRead, {
+    readonly kind: "malformed";
+}>;
+
 declare type ProviderId = KnownProvider | string;
 
 /**

package/dist/kay-agent-testing.js

@@ -1,3 +1,102 @@
+// packages/herd-agent/dist/core/tools/tool-parameters.js
+import { z } from "zod";
+var URI_PAYLOAD_MARKER = "x-kay-uri-payload";
+var uriPayloadSchema = z.union([
+  z.string(),
+  z.record(z.string(), z.unknown()),
+  z.array(z.unknown()),
+  z.number(),
+  z.boolean(),
+  z.null()
+]).meta({ [URI_PAYLOAD_MARKER]: true });
+
+// 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 };
+}
+
+// packages/herd-agent/dist/core/is-object.js
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/herd-agent/dist/core/tools/produced-resources.js
+var DECLARATIONS = Symbol.for("herd.producedResources.declarations");
+function recordProducedResources(details) {
+  if (!isObject(details))
+    return unchanged(details);
+  const channel = channelOf(details);
+  const droppedPayloadValue = Object.hasOwn(details, PRODUCED_RESOURCES_DETAILS_KEY);
+  if (channel === void 0 && !droppedPayloadValue)
+    return unchanged(details);
+  const recorded = Object.fromEntries(Object.entries(details).filter(([key]) => key !== PRODUCED_RESOURCES_DETAILS_KEY));
+  let malformedClaim = false;
+  if (channel !== void 0) {
+    const claims = claimsFrom(channel);
+    if (claims.length > 0) {
+      recorded[PRODUCED_RESOURCES_DETAILS_KEY] = claims;
+      malformedClaim = !claims.every(isProducedResourceDeclaration);
+    }
+  }
+  return { details: recorded, droppedPayloadValue, malformedClaim };
+}
+function unchanged(details) {
+  return { details, droppedPayloadValue: false, malformedClaim: false };
+}
+function channelOf(details) {
+  return Object.hasOwn(details, DECLARATIONS) ? details[DECLARATIONS] : void 0;
+}
+function claimsFrom(claimed) {
+  try {
+    return Array.isArray(claimed) ? Array.from(claimed, snapshotClaim) : [snapshotClaim(claimed)];
+  } catch (error) {
+    return [`<unreadable claim: ${typeof error}>`];
+  }
+}
+function snapshotClaim(value) {
+  if (!isObject(value))
+    return jsonValue(value);
+  const copy = Object.fromEntries(Object.entries(value).map(([key, field]) => [key, jsonValue(field)]));
+  return isProducedResourceDeclaration(copy) ? Object.freeze({ uri: copy.uri, action: copy.action }) : Object.freeze(copy);
+}
+function jsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return `<${Array.isArray(value) ? "array" : typeof value}>`;
+}
+
 // packages/herd-agent/dist/testing.js
 function fauxAuthContext(overrides = {}) {
   return {
@@ -81,8 +180,18 @@ function defaultTestToolContext() {
 async function invokeToolForTest(tool, params, ctx = defaultTestToolContext()) {
   return tool.execute("test-call", params, void 0, void 0, ctx);
 }
+function producedResourcesForTest(result) {
+  const recorded = recordProducedResources(result.details).details;
+  const read = readProducedResourceDeclarations(recorded);
+  if (read.kind === "malformed") {
+    const claim = recorded[PRODUCED_RESOURCES_DETAILS_KEY];
+    throw new TypeError(`The tool declared produced resources the contract refuses, so a run would report a gap for this call: ${JSON.stringify(claim)}. Each declaration must be exactly { uri, action }, where uri is a scheme:// URI or an absolute local path with no surrounding whitespace and action is "created" or "updated".`);
+  }
+  return read;
+}
 export {
   fauxAuthContext,
   fauxKayAgentCapabilities,
-  invokeToolForTest
+  invokeToolForTest,
+  producedResourcesForTest
 };

package/dist/kay-agent.d.ts

@@ -595,6 +595,27 @@ export declare interface CurrentResourceState {
     readonly content?: string | Uint8Array;
 }
 
+/**
+ * Declare the URIs a tool call created or updated as a side effect, on the result it returns.
+ *
+ * The declarations ride the result to the host, which records them in the transcript under the
+ * reserved `producedResources` details key, so an automation run lists them beside the URIs its
+ * `write` and `edit` calls changed. A declaration the contract refuses (not exactly `{ uri, action }`,
+ * a URI that is neither `scheme://…` nor an absolute local path, an unknown action) never fails the
+ * call, because its effect has already happened: the host records the call's claim as malformed,
+ * the run reports a gap for it, and the session logs a warning. A tool never writes the reserved key
+ * itself; the host drops whatever a result's own details hold there. Declarations ride only a
+ * returned result: a call that throws declares nothing.
+ *
+ * @param result The result the tool returns. Its `details` must be an object or `undefined`;
+ *   `undefined` becomes an empty object that carries the declarations.
+ * @param declarations Each names a `scheme://` URI or an absolute local path, compared as an
+ *   exact string, and whether the call `created` or `updated` it.
+ * @returns A copy of `result` carrying these declarations after any it already carried.
+ * @throws TypeError when `details` is neither an object nor `undefined`, which the types rule out.
+ */
+export declare function declareProducedResources<TDetails extends object | undefined>(result: AgentToolResult<TDetails>, declarations: readonly ProducedResourceDeclaration[]): AgentToolResult<DetailsWithProducedResources<TDetails>>;
+
 /**
  * The one-liner for an auth-gated tool (decision 002 addendum, F-19). Composes
  * {@link toolParameters}, {@link withResolvedAuth}, and `schema.parse` so `body` receives a
@@ -685,6 +706,9 @@ declare interface DerivedToolClassification {
  */
 export declare function describeUriTextEditTarget(grammar: UriTextEditGrammar, index: number, count: number): string;
 
+/** `details` once it carries declarations: an `undefined` input becomes an empty object. */
+export declare type DetailsWithProducedResources<TDetails> = TDetails extends undefined ? Record<string, never> : TDetails;
+
 /**
  * The execute-time auth surface the SDK wrappers read off `ctx.auth`. Slice 3 attaches a
  * concrete implementation (vault + pkce refresh + active-account store) to ExtensionContext;
@@ -2855,6 +2879,7 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
             fallback: z.ZodArray<z.ZodObject<{
@@ -2871,6 +2896,7 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
@@ -3122,6 +3148,19 @@ export declare type PluginToolDefinition<TParams extends ToolParametersWire = To
     readonly execute: (toolCallId: string, params: ToolExecutionAwareParams<InferToolInput<TParams>>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ToolContext) => Promise<AgentToolResult<TDetails>>;
 };
 
+/**
+ * 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`.
+ */
+export declare type ProducedResourceAction = "created" | "updated";
+
+/** One URI a tool call created or updated as a side effect. */
+export declare interface ProducedResourceDeclaration {
+    /** A `scheme://…` URI or an absolute local file path, compared as an exact string. */
+    readonly uri: string;
+    readonly action: ProducedResourceAction;
+}
+
 declare type ProviderId = KnownProvider | string;
 
 /**

package/dist/kay-agent.js

@@ -115,6 +115,26 @@ function filesystemStampDigest(revision) {
   return parts.length === 6 ? parts[5] : void 0;
 }
 
+// packages/herd-uri/dist/produced-resources.js
+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");
+}
+
 // packages/herd-uri/dist/template-route.js
 var PLACEHOLDER_RE = /<([^<>]+)>/g;
 var REST_SUFFIX = "...";
@@ -887,6 +907,59 @@ function toToolParameters(schema) {
   return rest;
 }
 
+// packages/herd-agent/dist/core/is-object.js
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/herd-agent/dist/core/tools/produced-resources.js
+var DECLARATIONS = Symbol.for("herd.producedResources.declarations");
+function declareProducedResources(result, declarations) {
+  const details = declarableDetails(result.details);
+  const claims = [...claimsOn(details), ...claimsFrom(declarations)];
+  const next = { ...details };
+  if (claims.length > 0)
+    next[DECLARATIONS] = Object.freeze(claims);
+  return {
+    ...result,
+    details: next
+  };
+}
+function declarableDetails(details) {
+  if (details === void 0)
+    return {};
+  if (!isObject(details)) {
+    throw new TypeError(`declareProducedResources needs a tool result whose details is an object or undefined, not ${Array.isArray(details) ? "an array" : typeof details}.`);
+  }
+  return details;
+}
+function channelOf(details) {
+  return Object.hasOwn(details, DECLARATIONS) ? details[DECLARATIONS] : void 0;
+}
+function claimsOn(details) {
+  const channel = channelOf(details);
+  return channel === void 0 ? [] : claimsFrom(channel);
+}
+function claimsFrom(claimed) {
+  try {
+    return Array.isArray(claimed) ? Array.from(claimed, snapshotClaim) : [snapshotClaim(claimed)];
+  } catch (error) {
+    return [`<unreadable claim: ${typeof error}>`];
+  }
+}
+function snapshotClaim(value) {
+  if (!isObject(value))
+    return jsonValue(value);
+  const copy = Object.fromEntries(Object.entries(value).map(([key, field]) => [key, jsonValue(field)]));
+  return isProducedResourceDeclaration(copy) ? Object.freeze({ uri: copy.uri, action: copy.action }) : Object.freeze(copy);
+}
+function jsonValue(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return `<${Array.isArray(value) ? "array" : typeof value}>`;
+}
+
 // packages/plugin-primitives/dist/results.js
 function textResult(text, details) {
   const content = [{ type: "text", text }];
@@ -1309,6 +1382,7 @@ export {
   contentResult,
   createFallbackOnlyWithJev,
   createJsonApiClient,
+  declareProducedResources,
   defineAuthedTool,
   defineKayAgentAdvertisement,
   defineTool,

package/dist/kay-app.d.ts

@@ -1393,6 +1393,36 @@ export declare type KayAppAutomationMatch = {
     readonly requestedBy?: "user" | "agent" | undefined;
 };
 
+/**
+ * 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
+ * {@link KayAppAutomationRunDetail.artifacts} and `externalResources` report,
+ * deduplicated by URI. A session-scoped `output://` URI is one row per session.
+ * `uri` is a `scheme://` URI, an absolute local file path, or an external
+ * resource's canonical https URL.
+ */
+export declare interface KayAppAutomationProducedResourceItem {
+    readonly uri: string;
+    /** By precedence `deleted` > `created` > `updated`; only an artifact receipt reports `deleted`. */
+    readonly action: "created" | "updated" | "deleted";
+    /** The session that produced it, and the one a session-scoped URI resolves against. */
+    readonly sessionId: string;
+    /** A real revision the run recorded for this URI, and how many; absent when it recorded none. */
+    readonly revision?: {
+        readonly id: string;
+        readonly count: number;
+    } | undefined;
+    readonly offBranch: boolean;
+    readonly shared: boolean;
+}
+
+/** Every URI one run produced, served whole: at most 1,000 rows, `truncated` when there were more. */
+export declare interface KayAppAutomationProducedResources {
+    readonly items: readonly KayAppAutomationProducedResourceItem[];
+    readonly totalCount: number;
+    readonly truncated: boolean;
+}
+
 export declare interface KayAppAutomationRun {
     readonly id: string;
     readonly bindingId: string;
@@ -1433,6 +1463,8 @@ export declare interface KayAppAutomationRunDetail {
      * because a pull request is something the run produced.
      */
     readonly externalResources: KayAppProvenancePage<KayAppAutomationExternalResourceItem>;
+    /** The one list of everything the run produced; it includes every row of the two lists above. */
+    readonly producedResources: KayAppAutomationProducedResources;
     readonly suggestions: KayAppProvenancePage<KayAppAutomationSuggestionItem>;
     readonly coverage: KayAppAutomationRunCoverage;
 }
@@ -2602,7 +2634,9 @@ export declare type KayAppProcessingSpeed = "standard" | "fast";
  */
 export declare type KayAppProvenanceGapCode = "legacy-run-id-missing" | "mutation-revision-missing" | "partial-git-provenance" | "git-session-stamp-missing"
 /** A run created something off this machine that the transcript cannot name. */
-| "external-resource-unnamed" | "skill-suggestion-unattributable" | "malformed-source-record" | "source-unreadable" | "git-revision-unavailable" | "automation-history-unavailable" | "session-history-unavailable" | "required-evidence-missing";
+| "external-resource-unnamed"
+/** A run's write or edit succeeded and the transcript cannot name the URI it changed. */
+| "produced-resource-unnamed" | "skill-suggestion-unattributable" | "malformed-source-record" | "source-unreadable" | "git-revision-unavailable" | "automation-history-unavailable" | "session-history-unavailable" | "required-evidence-missing";
 
 /** One gap, with enum-specific bounded detail; never a raw payload. */
 export declare interface KayAppProvenanceGapSummary {
@@ -2839,7 +2873,7 @@ export declare type KayAppSessionEventType = "human-message" | "turn-settled" |
 
 export declare type KayAppSessionIntent = SessionIntent;
 
-export declare type KayAppSessionMode = "default" | "ask" | "allow";
+export declare type KayAppSessionMode = "default" | "ask" | "allow" | "auto";
 
 export declare type KayAppSessionOrigin = {
     readonly kind: "user";
@@ -4367,6 +4401,7 @@ declare const PluginAgentDefinitionPermissionRule: z.ZodObject<{
         default: "default";
         allow: "allow";
         ask: "ask";
+        auto: "auto";
     }>>;
 }, z.core.$strict>;
 

package/package.json

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