@hasna/skills 0.5.7 → 0.5.8

package/README.md

@@ -522,7 +522,10 @@ the same declaration, and an uncertain upload is never sent twice. If a process
 crashes while holding `operation.lock`, confirm it has stopped before removing
 that lock explicitly. Status and cancellation remain available when new
 publishing is disabled. Exit 2 means publication is still pending; `committed`
-means source was published. Private execution remains unavailable.
+means source was published. Execution requires a separate server quote and approval.
+Publication recovery results report `executionEnabled: null` because their durable
+receipts contain no server capability observation. Use `getCapability()` for the
+server's current boolean capability; it does not authorize an individual run.
 
 The SDK exports `RemotePrivatePublicationsClient` through both the root and
 `./sdk`; `RemoteSkillsAuthClient.openPrivatePublications` creates one from fresh
@@ -1193,3 +1196,46 @@ returned or saved by the tools.
 
 These clients still require deployed configuration and controlled real recipient
 email acceptance before recovery can be offered as a live product capability.
+
+### Injected operation transport
+
+`@hasna/skills/sdk` exports `createSkillOperationClient` for an embedder-supplied
+`SkillOperationTransport`. It provides a bounded JSON envelope, immutable
+snapshots and explicit status lookup. It does not connect to a provider, discover
+an endpoint, read credentials, or provide guest IPC or authorization.
+
+```ts
+import { createSkillOperationClient, type SkillOperationTransport } from "@hasna/skills/sdk";
+
+function operationsForCapturedRun(transport: SkillOperationTransport) {
+  return createSkillOperationClient(transport, { timeoutMs: 30_000 });
+}
+// The embedder supplies invoke(request, { signal }) and get(requestId, { signal }).
+// invoke accepts { contractVersion: 1, requestId: UUID, operation: "text.generate",
+//                  input: { prompt: "..." } }.
+```
+
+Create one client per captured authority scope. The transport must enforce that
+scope, bind the request ID to the exact payload durably, and enforce approval,
+budget and execution policy. The client remembers up to 256 request identities
+and 1 MiB of canonical requests. It refuses capacity before transport and never
+evicts an old identity. An explicit repeat with the same payload makes one new
+transport call; a changed payload under a remembered ID is refused locally.
+This local check does not replace server deduplication.
+
+Requests are limited to 64 KiB and responses to 1 MiB of serialized UTF-8 JSON,
+with depth and node limits exported in `SKILL_OPERATION_LIMITS`. Plain JSON data
+is copied and deeply frozen; cycles, accessors, `toJSON` functions, unsupported
+values and extra envelope fields are refused. Ordinary data inside `input` and
+`output` is preserved. Request IDs use canonical lowercase UUID strings;
+operation names use lowercase letters, digits and dot or hyphen separators.
+
+Responses preserve `contractVersion` and `requestId`. A status of `succeeded`
+includes `output`; `refused` includes a fixed `SkillOperationRefusal` code.
+`pending`, `unknown` and authoritative `not-executed` have no additional fields.
+Transport failure, in-flight abort and timeout produce a safe
+`SkillOperationClientError` with an unknown outcome. They never prove that an
+operation did not execute. The client does not retry or issue a status read
+automatically: explicitly call `get` with the same request ID to reconcile.
+Aborting locally does not establish server cancellation. An already-aborted
+signal refuses before calling the transport.

package/bin/index.js

@@ -36860,7 +36860,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.5.7",
+    version: "0.5.8",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -72952,7 +72952,7 @@ var init_mcp_contracts = __esm(() => {
   ].map((operation) => ({
     name: operation.name,
     title: operation.title,
-    description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; private execution remains unavailable.",
+    description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; execution requires a separate server quote and approval.",
     params: [...Object.keys(publicationVerification), ...Object.keys(operation.extras)],
     category: "storage",
     sideEffects: "filesystem",
@@ -72965,7 +72965,7 @@ var init_mcp_contracts = __esm(() => {
       state: { type: "string" },
       versionId: { oneOf: [publicationUuidSchema, { type: "null" }] },
       committed: { type: "boolean" },
-      executionEnabled: { const: false },
+      executionEnabled: { oneOf: [{ type: "boolean" }, { type: "null" }] },
       nextAction: { type: "string" }
     }, ["recoveryDirectory", "skillId", "intentId", "state", "versionId", "committed", "executionEnabled", "nextAction"])
   }));
@@ -74747,7 +74747,7 @@ class RemotePrivatePublicationsClient {
       return bad();
     const response = await boundedJson(skillsApiRequestUrl(this.apiOrigin, "/api/v1/capabilities"), {}, this.#token, false, options.timeoutMs, options.signal);
     const p = record7(response) && response.privatePublishing;
-    if (!record7(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || p.executionEnabled !== false)
+    if (!record7(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || typeof p.executionEnabled !== "boolean")
       throw new PrivatePublicationError("PUBLICATION_CONTRACT_UNAVAILABLE", "This server does not support the hosted private publication contract.");
     return Object.freeze({ ...p });
   }
@@ -75655,7 +75655,7 @@ async function preparePrivatePublication(client, sourceDirectory, recoveryDirect
 }
 function privatePublicationResult(directory, receipt) {
   const state = receipt.intent?.state ?? receipt.phase, committed = state === "committed";
-  const nextAction = committed ? "The version is published. Private execution remains unavailable." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
+  const nextAction = committed ? "Published; execution requires a separate server quote and approval." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
   return {
     recoveryDirectory: directory,
     skillId: receipt.skillId,
@@ -75663,7 +75663,7 @@ function privatePublicationResult(directory, receipt) {
     state,
     versionId: receipt.intent?.versionId ?? null,
     committed,
-    executionEnabled: false,
+    executionEnabled: null,
     nextAction
   };
 }

package/bin/mcp.js

@@ -5586,7 +5586,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/skills",
-    version: "0.5.7",
+    version: "0.5.8",
     description: "Skills library for AI coding agents",
     type: "module",
     bin: {
@@ -26861,7 +26861,7 @@ var init_mcp_contracts = __esm(() => {
   ].map((operation) => ({
     name: operation.name,
     title: operation.title,
-    description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; private execution remains unavailable.",
+    description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; execution requires a separate server quote and approval.",
     params: [...Object.keys(publicationVerification), ...Object.keys(operation.extras)],
     category: "storage",
     sideEffects: "filesystem",
@@ -26874,7 +26874,7 @@ var init_mcp_contracts = __esm(() => {
       state: { type: "string" },
       versionId: { oneOf: [publicationUuidSchema, { type: "null" }] },
       committed: { type: "boolean" },
-      executionEnabled: { const: false },
+      executionEnabled: { oneOf: [{ type: "boolean" }, { type: "null" }] },
       nextAction: { type: "string" }
     }, ["recoveryDirectory", "skillId", "intentId", "state", "versionId", "committed", "executionEnabled", "nextAction"])
   }));
@@ -31000,7 +31000,7 @@ class RemotePrivatePublicationsClient {
       return bad();
     const response = await boundedJson(skillsApiRequestUrl(this.apiOrigin, "/api/v1/capabilities"), {}, this.#token, false, options.timeoutMs, options.signal);
     const p = record7(response) && response.privatePublishing;
-    if (!record7(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || p.executionEnabled !== false)
+    if (!record7(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || typeof p.executionEnabled !== "boolean")
       throw new PrivatePublicationError("PUBLICATION_CONTRACT_UNAVAILABLE", "This server does not support the hosted private publication contract.");
     return Object.freeze({ ...p });
   }
@@ -32271,7 +32271,7 @@ async function preparePrivatePublication(client, sourceDirectory, recoveryDirect
 }
 function privatePublicationResult(directory, receipt) {
   const state = receipt.intent?.state ?? receipt.phase, committed = state === "committed";
-  const nextAction = committed ? "The version is published. Private execution remains unavailable." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
+  const nextAction = committed ? "Published; execution requires a separate server quote and approval." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
   return {
     recoveryDirectory: directory,
     skillId: receipt.skillId,
@@ -32279,7 +32279,7 @@ function privatePublicationResult(directory, receipt) {
     state,
     versionId: receipt.intent?.versionId ?? null,
     committed,
-    executionEnabled: false,
+    executionEnabled: null,
     nextAction
   };
 }

package/bin/migrate.js

@@ -7,7 +7,7 @@ import { join as join6 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.5.7",
+  version: "0.5.8",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/server.js

@@ -23100,7 +23100,7 @@ var init_dist_es9 = __esm(() => {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.5.7",
+  version: "0.5.8",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/bin/worker.js

@@ -23103,7 +23103,7 @@ import { randomUUID as randomUUID4 } from "crypto";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.5.7",
+  version: "0.5.8",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {

package/dist/index.js

@@ -13336,7 +13336,7 @@ import { dirname as dirname7, relative as relative4 } from "path";
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.5.7",
+  version: "0.5.8",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -14412,7 +14412,7 @@ var privatePublicationContracts = [
 ].map((operation) => ({
   name: operation.name,
   title: operation.title,
-  description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; private execution remains unavailable.",
+  description: "Manage private source publication with fresh workspace verification and durable host-local recovery. Upload consent and current version comparison are explicit; execution requires a separate server quote and approval.",
   params: [...Object.keys(publicationVerification), ...Object.keys(operation.extras)],
   category: "storage",
   sideEffects: "filesystem",
@@ -14425,7 +14425,7 @@ var privatePublicationContracts = [
     state: { type: "string" },
     versionId: { oneOf: [publicationUuidSchema, { type: "null" }] },
     committed: { type: "boolean" },
-    executionEnabled: { const: false },
+    executionEnabled: { oneOf: [{ type: "boolean" }, { type: "null" }] },
     nextAction: { type: "string" }
   }, ["recoveryDirectory", "skillId", "intentId", "state", "versionId", "committed", "executionEnabled", "nextAction"])
 }));
@@ -16119,7 +16119,7 @@ class RemotePrivatePublicationsClient {
       return bad();
     const response = await boundedJson(skillsApiRequestUrl(this.apiOrigin, "/api/v1/capabilities"), {}, this.#token, false, options.timeoutMs, options.signal);
     const p = record5(response) && response.privatePublishing;
-    if (!record5(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || p.executionEnabled !== false)
+    if (!record5(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p.contractVersion !== 1 || typeof p.enabled !== "boolean" || p.authentication !== "interactive-session" || p.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p.uploadMaxTtlSeconds !== 300 || typeof p.executionEnabled !== "boolean")
       throw new PrivatePublicationError("PUBLICATION_CONTRACT_UNAVAILABLE", "This server does not support the hosted private publication contract.");
     return Object.freeze({ ...p });
   }
@@ -16642,7 +16642,7 @@ async function preparePrivatePublication(client, sourceDirectory, recoveryDirect
 }
 function privatePublicationResult(directory, receipt) {
   const state = receipt.intent?.state ?? receipt.phase, committed = state === "committed";
-  const nextAction = committed ? "The version is published. Private execution remains unavailable." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
+  const nextAction = committed ? "Published; execution requires a separate server quote and approval." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
   return {
     recoveryDirectory: directory,
     skillId: receipt.skillId,
@@ -16650,7 +16650,7 @@ function privatePublicationResult(directory, receipt) {
     state,
     versionId: receipt.intent?.versionId ?? null,
     committed,
-    executionEnabled: false,
+    executionEnabled: null,
     nextAction
   };
 }

package/dist/lib/private-publication-recovery.d.ts

@@ -18,7 +18,8 @@ export interface PrivatePublicationResult {
     state: string;
     versionId: string | null;
     committed: boolean;
-    executionEnabled: false;
+    /** Null when this recovery receipt contains no directly observed server capability. Publication alone never proves execution availability. */
+    executionEnabled: boolean | null;
     nextAction: string;
 }
 /** Reads only two bounded local files. The receipt never contains a token or signed URL. */

package/dist/lib/remote-private-publications.d.ts

@@ -27,7 +27,8 @@ export interface PrivatePublishingCapability {
     authentication: "interactive-session";
     maxArchiveBytes: 16777216;
     uploadMaxTtlSeconds: 300;
-    executionEnabled: false;
+    /** Server capability only; each execution still requires a separate quote and approval. */
+    executionEnabled: boolean;
 }
 /** Contains a short-lived bearer capability. Never print or persist this object. */
 export interface PrivatePublicationUpload {

package/dist/sdk/index.d.ts

@@ -48,3 +48,4 @@ export { WorkspaceInvitationInputError, RemoteWorkspaceInvitationError, RemoteWo
 export { InvitationEmailInputError, RemoteInvitationEmailError, RemoteInvitationEmailUnconfirmedError, type RequestInvitationEmailChallenge, type AcceptInvitationEmailChallenge, type RemoteInvitationEmailChallenge, type RemoteInvitationEmailAcceptance, type RemoteInvitationEmailErrorCode } from "../lib/remote-invitation-recovery.js";
 export { RemotePrivatePublicationsClient, PrivatePublicationError, PRIVATE_PUBLICATION_MAX_BYTES, type PrivatePublicationDeclaration, type PrivatePublicationView, type PrivatePublicationState, type PrivatePublishingCapability } from "../lib/remote-private-publications.js";
 export { preparePrivatePublication, readPrivatePublicationRecovery, continuePrivatePublication, inspectPrivatePublication, type PrivatePublicationRecovery, type PrivatePublicationResult } from "../lib/private-publication-recovery.js";
+export { createSkillOperationClient, SkillOperationClientError, SKILL_OPERATION_LIMITS, type SkillOperationClient, type SkillOperationTransport, type SkillOperationRequest, type SkillOperationResult, type SkillOperationJson, type SkillOperationRefusal, type SkillOperationClientErrorCode } from "./operations.js";

package/dist/sdk/index.js

@@ -25496,7 +25496,7 @@ class MissingSkillsFleetError extends Error {
 // package.json
 var package_default = {
   name: "@hasna/skills",
-  version: "0.5.7",
+  version: "0.5.8",
   description: "Skills library for AI coding agents",
   type: "module",
   bin: {
@@ -54464,7 +54464,7 @@ class RemotePrivatePublicationsClient {
       return bad();
     const response = await boundedJson(skillsApiRequestUrl(this.apiOrigin, "/api/v1/capabilities"), {}, this.#token, false, options.timeoutMs, options.signal);
     const p2 = record5(response) && response.privatePublishing;
-    if (!record5(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p2, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p2.contractVersion !== 1 || typeof p2.enabled !== "boolean" || p2.authentication !== "interactive-session" || p2.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p2.uploadMaxTtlSeconds !== 300 || p2.executionEnabled !== false)
+    if (!record5(response) || response.contractVersion !== 1 || response.apiVersion !== 1 || !exact(p2, ["contractVersion", "enabled", "authentication", "maxArchiveBytes", "uploadMaxTtlSeconds", "executionEnabled"]) || p2.contractVersion !== 1 || typeof p2.enabled !== "boolean" || p2.authentication !== "interactive-session" || p2.maxArchiveBytes !== PRIVATE_PUBLICATION_MAX_BYTES || p2.uploadMaxTtlSeconds !== 300 || typeof p2.executionEnabled !== "boolean")
       throw new PrivatePublicationError("PUBLICATION_CONTRACT_UNAVAILABLE", "This server does not support the hosted private publication contract.");
     return Object.freeze({ ...p2 });
   }
@@ -54987,7 +54987,7 @@ async function preparePrivatePublication(client, sourceDirectory, recoveryDirect
 }
 function privatePublicationResult(directory, receipt) {
   const state = receipt.intent?.state ?? receipt.phase, committed = state === "committed";
-  const nextAction = committed ? "The version is published. Private execution remains unavailable." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
+  const nextAction = committed ? "Published; execution requires a separate server quote and approval." : ["rejected", "cancelled", "expired"].includes(state) ? "This intent is terminal. Inspect the result before explicitly preparing another version." : state === "needs_attention" ? "Keep this intent and contact the service operator; do not create a replacement or upload again." : receipt.phase === "upload_uncertain" ? "Run publication resume with this recovery directory to finalize the same intent without another upload." : receipt.intent ? "Run publication status or resume with this recovery directory; cancel explicitly if you want to stop." : "Run publication resume with this recovery directory to reconcile the identical request key and declaration.";
   return {
     recoveryDirectory: directory,
     skillId: receipt.skillId,
@@ -54995,7 +54995,7 @@ function privatePublicationResult(directory, receipt) {
     state,
     versionId: receipt.intent?.versionId ?? null,
     committed,
-    executionEnabled: false,
+    executionEnabled: null,
     nextAction
   };
 }
@@ -55061,6 +55061,206 @@ async function inspectLocked(client, directory, cancel) {
     throw new PrivatePublicationError("PUBLICATION_INTENT_UNKNOWN", "Reconcile the saved begin request with publication resume before cancelling its intent.");
   return privatePublicationResult(directory, receipt);
 }
+// src/sdk/operations.ts
+var SKILL_OPERATION_LIMITS = Object.freeze({ requestBytes: 65536, resultBytes: 1048576, depth: 32, nodes: 16384, rememberedRequests: 256, rememberedBytes: 1048576 });
+
+class SkillOperationClientError extends Error {
+  code;
+  outcome;
+  constructor(code, outcome) {
+    super(`Skill operation client: ${code}`);
+    this.code = code;
+    this.outcome = outcome;
+    this.name = "SkillOperationClientError";
+  }
+}
+var encoder = new TextEncoder;
+var refusalCodes = new Set(["NOT_ALLOWED", "APPROVAL_REQUIRED", "BUDGET_EXHAUSTED", "EXPIRED", "CANCELLED", "UNAVAILABLE", "INVALID_INPUT"]);
+var requestIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+function validId(value) {
+  return typeof value === "string" && requestIdPattern.test(value);
+}
+function record6(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function exact2(value, names) {
+  const keys = Object.keys(value).sort(), expected = [...names].sort();
+  return keys.length === expected.length && keys.every((key, index) => key === expected[index]);
+}
+function snapshot(value, maximum) {
+  let nodes4 = 0, bytes = 0;
+  const parts = [], ancestors = new Set;
+  const append = (part) => {
+    if (part.length > maximum - bytes)
+      throw Error();
+    bytes += encoder.encode(part).byteLength;
+    if (bytes > maximum)
+      throw Error();
+    parts.push(part);
+  };
+  function visit(input, depth) {
+    if (++nodes4 > SKILL_OPERATION_LIMITS.nodes || depth > SKILL_OPERATION_LIMITS.depth)
+      throw Error();
+    if (input === null || typeof input === "boolean") {
+      append(String(input));
+      return input;
+    }
+    if (typeof input === "number") {
+      if (!Number.isFinite(input))
+        throw Error();
+      append(JSON.stringify(input));
+      return Object.is(input, -0) ? 0 : input;
+    }
+    if (typeof input === "string") {
+      if (input.length > maximum - bytes || /[\ud800-\udfff]/u.test(input))
+        throw Error();
+      append(JSON.stringify(input));
+      return input;
+    }
+    if (!input || typeof input !== "object" || ancestors.has(input))
+      throw Error();
+    const array = Array.isArray(input), proto = Object.getPrototypeOf(input);
+    if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+      throw Error();
+    const keys = Reflect.ownKeys(input);
+    if (keys.length > SKILL_OPERATION_LIMITS.nodes + 1 || keys.some((key) => typeof key !== "string"))
+      throw Error();
+    ancestors.add(input);
+    try {
+      if (array) {
+        if (input.length > SKILL_OPERATION_LIMITS.nodes || keys.length !== input.length + 1)
+          throw Error();
+        const result2 = [];
+        append("[");
+        for (let i4 = 0;i4 < input.length; i4++) {
+          const descriptor = Object.getOwnPropertyDescriptor(input, String(i4));
+          if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+            throw Error();
+          if (i4)
+            append(",");
+          result2.push(visit(descriptor.value, depth + 1));
+        }
+        append("]");
+        return Object.freeze(result2);
+      }
+      const result = Object.create(null);
+      append("{");
+      for (const [i4, key] of keys.sort().entries()) {
+        const descriptor = Object.getOwnPropertyDescriptor(input, key);
+        if (!("value" in descriptor) || !descriptor.enumerable || /[\ud800-\udfff]/u.test(key) || key.length > maximum - bytes)
+          throw Error();
+        if (i4)
+          append(",");
+        append(JSON.stringify(key));
+        append(":");
+        result[key] = visit(descriptor.value, depth + 1);
+      }
+      append("}");
+      return Object.freeze(result);
+    } finally {
+      ancestors.delete(input);
+    }
+  }
+  const owned = visit(value, 0);
+  return { value: owned, canonical: parts.join(""), bytes };
+}
+function requestSnapshot(input) {
+  try {
+    const owned = snapshot(input, SKILL_OPERATION_LIMITS.requestBytes), value = owned.value;
+    if (!record6(value) || !exact2(value, ["contractVersion", "requestId", "operation", "input"]) || value.contractVersion !== 1 || !validId(value.requestId) || typeof value.operation !== "string" || value.operation.length > 128 || !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(value.operation) || !record6(value.input))
+      throw Error();
+    return { ...owned, value };
+  } catch {
+    throw new SkillOperationClientError("INVALID_REQUEST", "not-invoked");
+  }
+}
+function resultSnapshot(input, requestId) {
+  try {
+    const value = snapshot(input, SKILL_OPERATION_LIMITS.resultBytes).value;
+    if (!record6(value) || value.contractVersion !== 1 || value.requestId !== requestId)
+      throw Error();
+    const fields = ["contractVersion", "requestId", "status"];
+    if (value.status === "succeeded")
+      fields.push("output");
+    else if (value.status === "refused") {
+      fields.push("code");
+      if (!refusalCodes.has(value.code))
+        throw Error();
+    } else if (!["not-executed", "pending", "unknown"].includes(value.status))
+      throw Error();
+    if (!exact2(value, fields))
+      throw Error();
+    return value;
+  } catch {
+    throw new SkillOperationClientError("INVALID_RESPONSE", "unknown");
+  }
+}
+function createSkillOperationClient(transport, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 30000;
+  if (!transport || typeof transport.invoke !== "function" || typeof transport.get !== "function" || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60000)
+    throw new SkillOperationClientError("INVALID_CONFIGURATION", "not-invoked");
+  const invokeTransport = transport.invoke.bind(transport), getTransport = transport.get.bind(transport);
+  const identities = new Map;
+  let rememberedBytes = 0;
+  async function call(requestId, signal, invoke) {
+    if (signal?.aborted)
+      throw new SkillOperationClientError("ABORTED", "not-invoked");
+    const controller = new AbortController;
+    let timer;
+    const abort = () => controller.abort();
+    let onAbort = () => {};
+    const interrupted = new Promise((_, reject) => {
+      onAbort = () => reject(new SkillOperationClientError("UNKNOWN_OUTCOME", "unknown"));
+      controller.signal.addEventListener("abort", onAbort, { once: true });
+    });
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+      if (signal?.aborted)
+        throw new SkillOperationClientError("ABORTED", "not-invoked");
+      timer = setTimeout(abort, timeoutMs);
+      let pending;
+      try {
+        pending = invoke(controller.signal);
+      } catch {
+        pending = Promise.reject(new SkillOperationClientError("UNKNOWN_OUTCOME", "unknown"));
+      }
+      const owned = Promise.resolve(pending).then((value) => resultSnapshot(value, requestId), () => {
+        throw new SkillOperationClientError("UNKNOWN_OUTCOME", "unknown");
+      });
+      const result = await Promise.race([owned, interrupted]);
+      if (controller.signal.aborted)
+        throw new SkillOperationClientError("UNKNOWN_OUTCOME", "unknown");
+      return result;
+    } finally {
+      if (timer !== undefined)
+        clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      controller.signal.removeEventListener("abort", onAbort);
+      controller.abort();
+    }
+  }
+  return Object.freeze({
+    async invoke(input, requestOptions = {}) {
+      if (requestOptions.signal?.aborted)
+        throw new SkillOperationClientError("ABORTED", "not-invoked");
+      const owned = requestSnapshot(input), previous = identities.get(owned.value.requestId);
+      if (previous !== undefined && previous !== owned.canonical)
+        throw new SkillOperationClientError("REQUEST_CONFLICT", "not-invoked");
+      if (previous === undefined) {
+        if (identities.size >= SKILL_OPERATION_LIMITS.rememberedRequests || rememberedBytes + owned.bytes > SKILL_OPERATION_LIMITS.rememberedBytes)
+          throw new SkillOperationClientError("REQUEST_CAPACITY", "not-invoked");
+        identities.set(owned.value.requestId, owned.canonical);
+        rememberedBytes += owned.bytes;
+      }
+      return call(owned.value.requestId, requestOptions.signal, (signal) => invokeTransport(owned.value, { signal }));
+    },
+    async get(requestId, requestOptions = {}) {
+      if (!validId(requestId))
+        throw new SkillOperationClientError("INVALID_REQUEST", "not-invoked");
+      return call(requestId, requestOptions.signal, (signal) => getTransport(requestId, { signal }));
+    }
+  });
+}
 export {
   verifyContentHashFromEntries,
   validateRunLifecycleEvent,
@@ -55119,6 +55319,7 @@ export {
   createStore,
   createSpendService,
   createSkillsFetchHandler,
+  createSkillOperationClient,
   createServer,
   createRunStateMachine,
   createRunService,
@@ -55151,7 +55352,9 @@ export {
   SqliteRunExecutionStore,
   SqliteGovernanceStore,
   SkillsFleetCredentialError,
+  SkillOperationClientError,
   SkillBundleInspectionError,
+  SKILL_OPERATION_LIMITS,
   SKILL_BUNDLE_INSPECTION_LIMITS,
   SKILLS_LOCAL_OPT_IN_ENV_KEYS,
   SKILLS_APP,

package/dist/sdk/operations.d.ts

@@ -0,0 +1,68 @@
+/** Provider-neutral guest operation client. Authority and IPC belong to the embedder.
+ * No credentials, endpoint discovery, provider SDK, or automatic retry is provided.
+ */
+export type SkillOperationJson = null | boolean | number | string | readonly SkillOperationJson[] | {
+    readonly [key: string]: SkillOperationJson;
+};
+export declare const SKILL_OPERATION_LIMITS: Readonly<{
+    requestBytes: 65536;
+    resultBytes: 1048576;
+    depth: 32;
+    nodes: 16384;
+    rememberedRequests: 256;
+    rememberedBytes: 1048576;
+}>;
+export type SkillOperationRefusal = "NOT_ALLOWED" | "APPROVAL_REQUIRED" | "BUDGET_EXHAUSTED" | "EXPIRED" | "CANCELLED" | "UNAVAILABLE" | "INVALID_INPUT";
+export interface SkillOperationRequest {
+    readonly contractVersion: 1;
+    readonly requestId: string;
+    readonly operation: string;
+    readonly input: {
+        readonly [key: string]: SkillOperationJson;
+    };
+}
+interface OperationIdentity {
+    readonly contractVersion: 1;
+    readonly requestId: string;
+}
+export type SkillOperationResult = OperationIdentity & ({
+    readonly status: "not-executed" | "pending" | "unknown";
+} | {
+    readonly status: "succeeded";
+    readonly output: SkillOperationJson;
+} | {
+    readonly status: "refused";
+    readonly code: SkillOperationRefusal;
+});
+/** Implementations must authenticate the captured run/attempt separately. A
+ * not-executed response is authoritative proof, never a guess from transport loss. */
+export interface SkillOperationTransport {
+    invoke(request: SkillOperationRequest, options: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+    get(requestId: string, options: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+}
+export type SkillOperationClientErrorCode = "INVALID_REQUEST" | "REQUEST_CONFLICT" | "REQUEST_CAPACITY" | "ABORTED" | "UNKNOWN_OUTCOME" | "INVALID_RESPONSE" | "INVALID_CONFIGURATION";
+export declare class SkillOperationClientError extends Error {
+    readonly code: SkillOperationClientErrorCode;
+    readonly outcome: "not-invoked" | "unknown";
+    constructor(code: SkillOperationClientErrorCode, outcome: "not-invoked" | "unknown");
+}
+export interface SkillOperationClient {
+    invoke(request: SkillOperationRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<SkillOperationResult>;
+    get(requestId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SkillOperationResult>;
+}
+/** One client belongs to one captured authority scope. Remembered identities
+ * are bounded and never evicted. This is local misuse protection, not durable
+ * deduplication: the server must bind request IDs and payloads atomically.
+ * Each explicit call invokes transport once; uncertainty requires explicit get. */
+export declare function createSkillOperationClient(transport: SkillOperationTransport, options?: {
+    timeoutMs?: number;
+}): SkillOperationClient;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {