@yaklabs-ai/plugin-sdk 0.48.1 → 0.49.0

package/dist/uri.d.ts

@@ -0,0 +1,380 @@
+/**
+ * Stable digest of a read's content, the revision a module without one gets.
+ * Prefixed so a provider revision can never collide with it by accident.
+ */
+export declare function contentDigest(content: string | Uint8Array): string;
+
+export declare function createUnavailableUriCaller(message: string): PluginUriCaller;
+
+declare type JsonPrimitive = string | number | boolean | null;
+
+declare type JsonValue = JsonPrimitive | {
+    readonly [key: string]: JsonValue;
+} | readonly JsonValue[];
+
+declare interface LineRange {
+    readonly start: number;
+    readonly end: number;
+}
+
+declare interface LineSelector {
+    readonly ranges: readonly LineRange[];
+    readonly raw: boolean;
+}
+
+/**
+ * A source-native read of one URI, shaped for downstream indexing rather than
+ * direct model consumption. A module's read returns it in
+ * `RawResource.observations`, built from the same fetch as the content, once
+ * per document it wants indexed; absence means "not indexed".
+ *
+ * Gone signal: the index retires a doc when a read throws `UriNotFoundError`
+ * or an error whose `.status === 404`. A module whose vendor signals "gone"
+ * differently (HTTP 410, a 200-body `{ok:false}`/`archived:true`, a
+ * 403/404-ambiguous lost-access response) must translate that into one of
+ * those two shapes itself; losing access to a resource counts as gone too.
+ * A read that cannot build a complete observation (a secondary fetch failed)
+ * returns none rather than a partial one.
+ *
+ * Account-qualified identity: a module whose read can resolve against more
+ * than one connected account (the account selector is stripped before route
+ * parsing, so two accounts reading the same opaque provider id would
+ * otherwise collide on one doc key) must fold `ctx.auth.credential.accountId`
+ * into `uri` - e.g. `gmail://@<accountId>/threads/<threadId>` - never the
+ * user-renamable connection/selector label. `ctx.auth.credential` is the
+ * reliable source of the resolved account at a `requiresAuth` module's
+ * `read()`: it is always populated once auth resolution runs (an
+ * `authContext`-style check already throws first when no credential
+ * resolved). `ctx.connection` may ALSO be populated by dispatch - a
+ * connection-required module receives it whenever the host has a tracked
+ * connection for the account - so do not assume it is absent; a module that
+ * wants the human-facing label rather than the account id reads
+ * `ctx.connection?.displayName`.
+ *
+ * `accountId` is guaranteed stable only for the life of the stored credential
+ * record, not necessarily across a disconnect/reconnect of the same
+ * real-world provider account. A scheme that mints an opaque id at connect
+ * time (the default for an api-key or delegated scheme, absent a
+ * provider-derived override) gets a fresh id on every connect; a scheme that
+ * instead derives the id from provider data (an oauth2-pkce scheme supplying
+ * `resolveAccountId`, e.g. reading an OIDC `sub`) keeps the same id across
+ * reconnect. A module on a scheme without a provider-stable id has two honest
+ * choices: derive its own stable identity from provider data at read time
+ * (call the provider's own account/"who am I" endpoint with the resolved
+ * credential and fold THAT into `uri` instead of `accountId`), or
+ * account-qualify with `accountId` knowing a disconnect/reconnect of the same
+ * real-world account re-keys its documents under a new id rather than
+ * updating them in place - nothing on the host side reconciles the old and
+ * new keys.
+ */
+declare interface ObservationMaterial {
+    /** Canonical URI of the observed resource - may differ from the input URI. */
+    readonly uri: string;
+    /** Scheme-prefixed content type, e.g. `"github.pr"`, `"gmail.thread"`, `"wikipedia.article"`. */
+    readonly kind: string;
+    readonly title?: string;
+    /** Source-native seams: one element per message/comment/section, in source order. */
+    readonly text?: readonly string[];
+    /** ISO-8601 creation time; provenance only - not persisted by the store yet. */
+    readonly createdAt?: string;
+    /** ISO-8601 last-update time; provenance only - not persisted by the store yet. */
+    readonly updatedAt?: string;
+    /** Source-native revision/version marker, when the source exposes one. */
+    readonly version?: string;
+    /**
+     * How long this resource stays worth semantically searching, measured from
+     * the LAST time it was observed - not from when it was first indexed. Every
+     * observation of an unchanged resource pushes the deadline out again, so a
+     * thread that keeps getting read keeps living and a quiet one ages out.
+     *
+     * Retention is opt-in per resource: absent means the index keeps the
+     * resource until its source says it is gone. A route declares this only
+     * when staleness is real for that shape - a chat thread or an inbox
+     * conversation goes cold, a durable note the user wrote does not.
+     */
+    readonly retainForMs?: number;
+}
+
+/**
+ * Sessionless resource calls. Each call checks the calling target's exact scheme and verb grant.
+ * Results retain provider bytes, metadata and revisions; provider failures retain their URI tags.
+ * A cancellation or lost response does not prove a mutation was not applied.
+ */
+export declare interface PluginUriCaller {
+    read(input: string, options?: PluginUriReadOptions): Promise<RawResource>;
+    list(input: string, params?: UriListParams, options?: PluginUriCallOptions): Promise<UriListResult>;
+    search(input: string, params: UriSearchParams, options?: PluginUriCallOptions): Promise<UriSearchResult>;
+    write(input: string, content?: UriPayload | Uint8Array, options?: PluginUriWriteOptions): Promise<UriMutationResult | void>;
+    edit(input: string, payload: UriPayload, options?: PluginUriMutationOptions): Promise<UriMutationResult>;
+    delete(input: string, options?: PluginUriMutationOptions): Promise<UriMutationResult>;
+}
+
+export declare interface PluginUriCallOptions {
+    readonly cwd?: string;
+    readonly signal?: AbortSignal;
+}
+
+export declare interface PluginUriMutationOptions extends PluginUriCallOptions {
+    readonly expectedRevision?: string;
+}
+
+export declare interface PluginUriReadOptions extends PluginUriCallOptions {
+    readonly knownRevision?: string;
+}
+
+export declare interface PluginUriWriteOptions extends PluginUriMutationOptions {
+    readonly sources?: readonly UriWriteSource[];
+    readonly writeSource?: UriSourceDescriptor;
+}
+
+declare interface RawResource {
+    readonly uri: string;
+    readonly content: string | Uint8Array;
+    readonly mimeType: string;
+    readonly metadata?: RawResourceMetadata;
+    readonly selector?: SelectorDisposition;
+    /**
+     * The indexable forms of this resource, built from the same fetch as
+     * `content`: one per document the read wants indexed (a thread read offers
+     * one per message). Absent or empty means nothing is indexed. The read tool
+     * takes them off before the cache and the model; other host reads
+     * (out-of-band host reads) return them untouched.
+     */
+    readonly observations?: readonly ObservationMaterial[];
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /**
+     * A short name for the resource this call touched, for the transcript row; absent shows the
+     * address. Render-only: the host stamps it on the tool result's `details`, never in `content`.
+     */
+    readonly label?: UriResourceLabel;
+    /**
+     * Answer to a `read` called with `ctx.knownRevision`: the module checked the source's current
+     * revision and it equals `knownRevision`, so `content` is empty and `metadata.revision` equals
+     * `knownRevision`. Set it only when that check was made and matched; a module that cannot
+     * check cheaply, or that found a different revision, returns the full resource without it.
+     */
+    readonly unchanged?: true;
+}
+
+declare interface RawResourceCacheControl {
+    /** False marks degraded/fallback content that read-through caches must not store. */
+    readonly store?: boolean;
+}
+
+declare interface RawResourceIdentity {
+    readonly id: string;
+    readonly version: string;
+    readonly variantId?: string;
+}
+
+declare interface RawResourceMetadata {
+    readonly size?: number;
+    readonly finalUrl?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly notes?: readonly string[];
+    readonly cache?: RawResourceCacheControl;
+    /**
+     * The absolute local filesystem path the resource's bytes were read from,
+     * when the transport read them from local disk. Converter-facing
+     * provenance: finalize threads it into the content probe so a converter
+     * can direct shell tools at the file (e.g. archive extraction). Absent for
+     * remote/synthesized content.
+     */
+    readonly localPath?: string;
+    /**
+     * Opaque source-native revision suitable only for a later equality check.
+     * A host records it as the session's witness for this resource; when a
+     * module reports none, the host records a content digest of `content`
+     * instead (`contentDigest`, prefixed `sha256:`), which the module can
+     * reproduce at mutation time from the same content its read returns.
+     */
+    readonly revision?: string;
+    /**
+     * Opaque immutable identity for the exact resource bytes returned by a
+     * provider. Transport preserves it for observers; it never parses it.
+     */
+    readonly resourceIdentity?: RawResourceIdentity;
+    /**
+     * The resource's stable public address when `uri` reports something more
+     * specific than the address a consumer names it by - a retained revision
+     * (`skill://<id>/@revision/<version>`) served for a `skill://<source>/<name>`
+     * read. Present only when the two differ. Consumers that attribute by name
+     * (the read tool's `skillName` detail, and everything keyed off it) read
+     * this; consumers that need the exact bytes keep `uri`.
+     */
+    readonly canonicalUri?: string;
+}
+
+declare type SelectorDisposition = {
+    readonly kind: "deferred";
+    readonly window?: LineSelector;
+} | {
+    readonly kind: "applied";
+} | {
+    readonly kind: "invalid";
+    readonly message: string;
+};
+
+declare interface UriCacheInvalidation {
+    /** Drop cached entries whose cache URI starts with this prefix. */
+    readonly prefix?: string;
+    /** Drop the exact cache URI. */
+    readonly uri?: string;
+}
+
+declare interface UriCachePolicy {
+    /** Read-family cache TTL in milliseconds; absent or zero means not cached. */
+    readonly ttlMs?: number;
+    /** Mutation directive applied after a successful write/edit/delete. */
+    readonly invalidate?: readonly UriCacheInvalidation[];
+}
+
+declare interface UriListItem {
+    readonly uri: string;
+    readonly title?: string;
+    readonly summary?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly operations?: readonly UriOperation[];
+}
+
+declare interface UriListMetadata {
+    readonly totalCount?: number;
+    readonly totalCountLabel?: string;
+    readonly returnedCount?: number;
+    /**
+     * True when the provider could not search/enumerate the whole corpus for this
+     * page, so the result may be missing matches (e.g. a federated query that spans
+     * multiple stores and timed out part way). The caller should treat the result as
+     * partial and, where possible, narrow the scope. Omit when results are complete.
+     */
+    readonly incompleteSearch?: boolean;
+}
+
+declare interface UriListParams {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+
+declare interface UriListResult {
+    readonly uri: string;
+    readonly items: readonly UriListItem[];
+    readonly nextCursor?: string;
+    readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
+}
+
+/** Authoritative lifecycle facts for a successful record-like URI mutation. */
+declare interface UriMutationReceipt {
+    readonly uri: string;
+    readonly operation: "create" | "update" | "trash" | "restore" | "delete";
+    readonly state: "active" | "trashed" | "deleted";
+    readonly revision?: string;
+    readonly changedFields?: readonly string[];
+    readonly recoverable: boolean;
+    readonly recoveryUri?: string;
+    readonly originalUri?: string;
+    readonly restoreTarget?: string;
+}
+
+declare interface UriMutationResult {
+    readonly uri: string;
+    readonly summary?: string;
+    readonly resource?: RawResource | JsonValue;
+    readonly validation?: readonly UriValidationMessage[];
+    readonly metadata?: Record<string, unknown>;
+    /** Typed state/recovery evidence; successful callers may trust it without a proof read. */
+    readonly receipt?: UriMutationReceipt;
+    /** Opaque source-native revision after this successful mutation. */
+    readonly revision?: string;
+    /** Cached reads this mutation made stale; see {@link UriCachePolicy.invalidate}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "invalidate">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
+}
+
+declare type UriOperation = "help" | "read" | "write" | "edit" | "list" | "search" | "delete";
+
+declare type UriPayload = string | JsonValue;
+
+/**
+ * What a settled call touched, as a person would name it.
+ *
+ * `name` is the resource itself (`#lane-analytics`). `section` is the part of it the address
+ * reaches into (`thread`), and is absent when the address is the resource.
+ */
+declare interface UriResourceLabel {
+    readonly name: string;
+    readonly section?: string;
+}
+
+declare interface UriSearchItem {
+    readonly uri: string;
+    readonly title?: string;
+    readonly summary?: string;
+    /** Provider resource MIME type; absent when the source does not report one. */
+    readonly sourceMimeType?: string;
+    readonly score?: number;
+    readonly reason?: string;
+    readonly operations?: readonly UriOperation[];
+}
+
+declare interface UriSearchParams {
+    readonly query: string;
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+
+declare interface UriSearchResult {
+    readonly uri: string;
+    readonly query: string;
+    readonly items: readonly UriSearchItem[];
+    readonly nextCursor?: string;
+    /**
+     * Optional result-set metadata, mirroring {@link UriListResult.metadata}. Lets a
+     * search surface completeness signals such as {@link UriListMetadata.incompleteSearch}
+     * so the caller knows the matches may be partial.
+     */
+    readonly metadata?: UriListMetadata;
+    /** How long the host may cache this result; see {@link UriCachePolicy.ttlMs}. */
+    readonly cachePolicy?: Pick<UriCachePolicy, "ttlMs">;
+    /** The module's own markdown for this result, shown instead of the host's default rendering. */
+    readonly markdown?: string;
+    /** The touched resource's name for the transcript row, as on `RawResource.label`. */
+    readonly label?: UriResourceLabel;
+}
+
+/**
+ * What a copied resource IS, minus its bytes: the identity half of a mediated
+ * source. The host derives it once (filename inferred from the source address,
+ * `mimeType` carried from the source module's own `RawResource.mimeType`) and
+ * delivers it inside each `UriWriteSource`, and on `ctx.writeSource` for a
+ * `source` copy - so a remote sink can name and type what it stores without
+ * re-deriving either from raw bytes.
+ */
+declare interface UriSourceDescriptor {
+    readonly uri: string;
+    readonly filename: string;
+    readonly mimeType?: string;
+}
+
+declare interface UriValidationMessage {
+    readonly path?: string;
+    readonly message: string;
+}
+
+/** A mediated resource supplied beside structured write content without entering model context. */
+declare interface UriWriteSource extends UriSourceDescriptor {
+    readonly content: string | Uint8Array;
+}
+
+export { }

package/dist/uri.js

@@ -0,0 +1,81 @@
+// packages/herd-uri/dist/resource-witness.js
+import { createHash } from "node:crypto";
+function contentDigest(content) {
+  const hash = createHash("sha256");
+  hash.update(typeof content === "string" ? new TextEncoder().encode(content) : content);
+  return `${DIGEST_PREFIX}${hash.digest("base64url")}`;
+}
+var DIGEST_PREFIX = "sha256:";
+
+// packages/herd-uri/dist/operations.js
+import { z } from "zod";
+var URI_OPERATIONS = [
+  "help",
+  "read",
+  "write",
+  "edit",
+  "list",
+  "search",
+  "delete"
+];
+var UriOperationSchema = z.enum(URI_OPERATIONS);
+
+// packages/herd-uri/dist/help-schema.js
+import { z as z2 } from "zod";
+var UriContractJsonSchema = z2.record(z2.string(), z2.unknown());
+var UriParameterSchema = z2.strictObject({
+  name: z2.string().min(1),
+  in: z2.enum(["uri", "query", "selector"]),
+  required: z2.boolean(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema,
+  examples: z2.array(z2.unknown()).optional()
+});
+var UriPayloadContractSchema = z2.strictObject({
+  name: z2.string().min(1),
+  mediaType: z2.string().optional(),
+  description: z2.string().optional(),
+  schema: UriContractJsonSchema.optional(),
+  semanticConstraints: z2.array(z2.string().min(1)).min(1).optional(),
+  examples: z2.array(z2.unknown()).optional()
+});
+
+// packages/herd-uri/dist/text-edit.js
+import { z as z3 } from "zod";
+var findReplaceArm = z3.strictObject({
+  find: z3.string().min(1),
+  replace: z3.string(),
+  all: z3.boolean().optional()
+});
+var oldNewEntry = z3.strictObject({
+  oldText: z3.string().min(1),
+  newText: z3.string()
+});
+var uriTextEditPayloadArms = z3.union([
+  findReplaceArm,
+  z3.strictObject({ edits: z3.array(oldNewEntry).min(1) }),
+  oldNewEntry,
+  z3.array(oldNewEntry).min(1)
+]);
+
+// packages/herd-uri/dist/schema/to-json-schema.js
+import { z as z4 } from "zod";
+
+// packages/plugin-sdk/dist/uri.js
+function createUnavailableUriCaller(message) {
+  const unavailable = async () => {
+    throw new Error(message);
+  };
+  return {
+    read: unavailable,
+    list: unavailable,
+    search: unavailable,
+    write: unavailable,
+    edit: unavailable,
+    delete: unavailable
+  };
+}
+export {
+  contentDigest,
+  createUnavailableUriCaller
+};

package/dist/vendored-mcp.d.ts

@@ -901,6 +901,8 @@ declare interface UriResolveContext {
      * resolve a URI outside any verb call.
      */
     readonly sessionId?: string;
+    /** Host-stamped calling plugin; absent for session dispatch and resolver matching. */
+    readonly callerPluginId?: string;
     /**
      * WHO the dispatching session acts as, stamped by the host at the same dispatch site as
      * {@link UriResolveContext.sessionId} and just as un-influenceable by the caller - so a module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -17,6 +17,10 @@
       "types": "./dist/kay-app.d.ts",
       "default": "./dist/kay-app.js"
     },
+    "./uri": {
+      "types": "./dist/uri.d.ts",
+      "default": "./dist/uri.js"
+    },
     "./kay-app/session-summary": {
       "types": "./dist/kay-app-session-summary.d.ts",
       "default": "./dist/kay-app-session-summary.js"