@yaklabs-ai/plugin-sdk 0.10.0 → 0.12.2

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 {
@@ -27,11 +126,22 @@ function unwired(name) {
     throw new Error(`${name} is not wired in this test double; pass your own handle to exercise it`);
   };
 }
+var NOT_WIRED = async () => ({ ok: false, reason: "unavailable", message: "not wired" });
+var UNWIRED_SURFACE = {
+  isAvailable: async () => false,
+  targets: NOT_WIRED,
+  observe: NOT_WIRED,
+  act: NOT_WIRED,
+  screenshot: NOT_WIRED,
+  open: NOT_WIRED
+};
 function fauxKayAgentCapabilities() {
   return {
     filesystem: {
       readText: unwired("filesystem.readText"),
       writeText: unwired("filesystem.writeText"),
+      readBytes: unwired("filesystem.readBytes"),
+      writeBytes: unwired("filesystem.writeBytes"),
       mkdir: unwired("filesystem.mkdir"),
       readDir: unwired("filesystem.readDir"),
       stat: unwired("filesystem.stat"),
@@ -62,6 +172,9 @@ function fauxKayAgentCapabilities() {
         remove: unwired("whiteboard.remove")
       })
     },
+    // Answers `unavailable` rather than rejecting: the real surfaces report an unavailable
+    // surface as `{ ok: false }`, never a throw. A test driving one overrides this handle.
+    interaction: { browserPane: UNWIRED_SURFACE, desktop: UNWIRED_SURFACE },
     interceptToolCall: () => void 0,
     // The one handle that does NOT refuse on use. `withJev`'s contract is that it always produces
     // the baseline, so a rejecting double would make a plugin's Jev path untestable and teach the
@@ -81,8 +194,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
 };