stitchkit 0.93.0 → 0.94.1

package/dist/index-7p1f0vp2.js

@@ -0,0 +1,154 @@
+import {
+  base64UrlToBytes,
+  bytesToBase64Url
+} from "./index-rxfy4cq7.js";
+import {
+  defineContract
+} from "./index-k30h66yd.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode
+} from "./index-2vtcmrj9.js";
+import {
+  mapObjectTypeBoundary,
+  transportResult,
+  typedEntries
+} from "./index-hffjpmq9.js";
+// src/contract/errors-factory.ts
+import { z } from "zod";
+function isErrorDetailsSchema(value) {
+  return value instanceof z.ZodObject || value instanceof z.ZodOptional && value.unwrap() instanceof z.ZodObject;
+}
+function validateDefinition(code, definition) {
+  if (!Number.isInteger(definition.status) || definition.status < 400 || definition.status > 599) {
+    throw new Error(`[stitchkit] Error "${code}" must declare an integer HTTP status from 400 to 599`);
+  }
+  if (definition.details !== undefined && !isErrorDetailsSchema(definition.details)) {
+    throw new Error(`[stitchkit] Error "${code}" details must be a Zod object or optional Zod object`);
+  }
+  if (definition.message !== undefined && (typeof definition.message !== "string" || definition.message.trim() === "")) {
+    throw new Error(`[stitchkit] Error "${code}" message must be a non-empty string`);
+  }
+}
+function defineErrors(source, mapping) {
+  const definitions = mapObjectTypeBoundary(source, (code, definition) => {
+    const name = String(code);
+    validateDefinition(name, definition);
+    return Object.freeze({ ...definition });
+  });
+  Object.freeze(definitions);
+  const errors = mapObjectTypeBoundary(definitions, (code, definition) => {
+    const name = String(code);
+    return (options = {}) => {
+      const message = options.message ?? definition.message;
+      if (definition.details === undefined) {
+        if ("details" in options) {
+          throw new Error(`[stitchkit] Error "${name}" does not declare details`);
+        }
+        return new AppError(name, message, definition.status, undefined, options.hint, undefined, definition.retryable);
+      }
+      const details = definition.details.parse(options.details);
+      return new AppError(name, message, definition.status, details, options.hint, undefined, definition.retryable);
+    };
+  });
+  Object.freeze(errors);
+  const codes = mapObjectTypeBoundary(definitions, (code) => String(code));
+  Object.freeze(codes);
+  const known = new Set(Object.keys(definitions));
+  for (const [code, target] of Object.entries(mapping?.map ?? {})) {
+    if (!isStitchErrorCode(code)) {
+      throw new Error(`[stitchkit] Error vocabulary contains unknown framework code "${code}"`);
+    }
+    if (typeof target !== "string" || !known.has(target)) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${code}" to undeclared code "${String(target)}"`);
+    }
+    const status = STITCH_ERROR_STATUS[code];
+    if (definitions[target]?.status !== status) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${code}" (${status}) to "${target}", declared with status ${String(definitions[target]?.status)}`);
+    }
+  }
+  for (const [statusText, target] of Object.entries(mapping?.fallback ?? {})) {
+    const status = Number(statusText);
+    if (!Number.isInteger(status) || status < 400 || status > 599) {
+      throw new Error(`[stitchkit] Error vocabulary fallback status "${statusText}" must be an integer from 400 to 599`);
+    }
+    if (typeof target !== "string" || !known.has(target)) {
+      throw new Error(`[stitchkit] Error vocabulary fallback ${status} names undeclared code "${String(target)}"`);
+    }
+    if (definitions[target]?.status !== status) {
+      throw new Error(`[stitchkit] Error vocabulary fallback ${status} must name a code with status ${status}`);
+    }
+  }
+  if (mapping?.exhaustive === true) {
+    for (const code of Object.keys(STITCH_ERROR_STATUS)) {
+      if (!Object.hasOwn(mapping.map, code)) {
+        throw new Error(`[stitchkit] Exhaustive error vocabulary is missing "${code}"`);
+      }
+    }
+  }
+  const codeMap = {};
+  for (const [stitchCode, status] of typedEntries(STITCH_ERROR_STATUS)) {
+    const code = mapping?.map?.[stitchCode] ?? mapping?.fallback?.[status];
+    if (code === undefined)
+      continue;
+    if (!known.has(code)) {
+      throw new Error(`[stitchkit] Error vocabulary maps "${stitchCode}" to undeclared code "${code}"`);
+    }
+    codeMap[stitchCode] = code;
+  }
+  Object.freeze(codeMap);
+  const vocabularyCodeMap = transportResult(codeMap);
+  return Object.freeze({
+    errors,
+    codes,
+    definitions,
+    isCode: (code) => known.has(code),
+    codeMap: vocabularyCodeMap
+  });
+}
+// src/contract/factory.ts
+function createContractFactory(config) {
+  const scoped = (meta, endpoints) => {
+    const validated = defineContract({ prefix: meta.prefix }, endpoints);
+    return {
+      endpoints: validated.endpoints,
+      meta: { ...meta, prefix: meta.prefix, scope: meta.scope }
+    };
+  };
+  if (config?.toolExposure !== "explicit")
+    return { defineContract: scoped };
+  const explicit = (meta, endpoints) => {
+    const materialized = mapObjectTypeBoundary(endpoints, (_key, endpoint) => endpoint.expose ? endpoint : { ...endpoint, expose: ["HTTP"] });
+    return scoped(meta, materialized);
+  };
+  return { defineContract: explicit };
+}
+// src/contract/pagination.ts
+import { z as z2 } from "zod";
+function paginatedSchema(itemSchema) {
+  return z2.object({
+    items: z2.array(itemSchema),
+    nextCursor: z2.string().nullable()
+  });
+}
+function toBase64Url(str) {
+  return bytesToBase64Url(new TextEncoder().encode(str));
+}
+function fromBase64Url(value) {
+  return new TextDecoder().decode(base64UrlToBytes(value));
+}
+function encodeCursor(value) {
+  return toBase64Url(JSON.stringify(value));
+}
+function decodeCursor(cursor, schema) {
+  if (!cursor)
+    return null;
+  try {
+    const parsed = schema.safeParse(JSON.parse(fromBase64Url(cursor)));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+export { defineErrors, createContractFactory, paginatedSchema, encodeCursor, decodeCursor };

package/dist/index-83bdg97s.js

@@ -0,0 +1,16 @@
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/internal/error-message.ts
+function messageOf(value) {
+  if (value instanceof Error)
+    return value.message;
+  if (typeof value === "string")
+    return value;
+  if (isRecord(value) && typeof value.message === "string")
+    return value.message;
+  return "";
+}
+
+export { messageOf };

package/dist/index-863ea9jb.js

@@ -0,0 +1,154 @@
+import {
+  AgentToolError,
+  resolveToolDurability
+} from "./index-79z7m7dt.js";
+import {
+  collectToolSurface
+} from "./index-hmp4800j.js";
+import {
+  createToolRunner,
+  formatToolError
+} from "./index-khtgb21r.js";
+import {
+  isToolExecutionControlError,
+  toolCauseFromResult,
+  toolResultFromError
+} from "./index-55hkhm67.js";
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/tools/agent.ts
+import { jsonSchema, tool } from "ai";
+function mountAgent(services, config = {}) {
+  const serviceList = Array.isArray(services) ? services : [services];
+  if (config.registry && config.runtimeTools) {
+    throw new Error("mountAgent accepts either runtimeTools or a registry, not both");
+  }
+  const runtimeTools = config.registry ? config.registry.tools : config.runtimeTools;
+  const tools = {};
+  const runTool = createToolRunner({
+    source: "agent",
+    toolSurface: true,
+    extend: config.extend,
+    context: config.context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip
+  });
+  for (const entry of collectToolSurface({
+    surface: { services: serviceList, runtimeTools },
+    transport: "AGENT",
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  })) {
+    const { mountable } = entry;
+    const inputSchema = jsonSchema(mountable.presentationSchema, {
+      validate: async (value) => isRecord(value) ? { success: true, value } : { success: false, error: new Error("Tool arguments must be an object") }
+    });
+    const execute = async (rawArgs, options) => {
+      const args = isRecord(rawArgs) ? rawArgs : {};
+      const durability = resolveToolDurability(options.context, options.toolCallId, options.abortSignal) ?? config.durability?.(options.toolCallId, options.abortSignal);
+      const callContext = { signal: options.abortSignal, toolCallId: options.toolCallId };
+      const executeTool = durability ? createToolRunner({
+        source: "agent",
+        toolSurface: true,
+        extend: config.extend,
+        context: {
+          ...config.context,
+          step: durability.step.bind(durability),
+          sleep: durability.sleep.bind(durability),
+          waitFor: durability.waitFor.bind(durability)
+        },
+        hooks: config.hooks,
+        lifecycle: config.lifecycle,
+        coerceJsonArgs: config.coerceJsonArgs,
+        onOutputStrip: config.onOutputStrip
+      }) : runTool;
+      const result = await executeTool(mountable, args, callContext).catch((err) => {
+        if (isToolExecutionControlError(err))
+          throw err;
+        throw new AgentToolError(formatToolError(toolResultFromError(err), mountable.name, config.errorHint), err);
+      });
+      if (result.ok)
+        return result.data;
+      throw new AgentToolError(formatToolError(result, mountable.name, config.errorHint), toolCauseFromResult(result));
+    };
+    const presenter = entry.kind === "runtime" ? entry.definition.present?.agent : undefined;
+    if (entry.kind === "runtime" && presenter) {
+      const { definition } = entry;
+      const output = definition.output;
+      if (!output) {
+        throw new Error(`Runtime tool "${definition.name}" presenter requires an output schema`);
+      }
+      tools[definition.name] = tool({
+        description: definition.description,
+        inputSchema,
+        outputSchema: output,
+        execute,
+        toModelOutput: async ({ output: rawOutput }) => {
+          const parsed = output.safeParse(rawOutput);
+          if (!parsed.success) {
+            return { type: "text", value: JSON.stringify(rawOutput) };
+          }
+          return presenter(parsed.data);
+        }
+      });
+    } else {
+      const output = entry.kind === "runtime" ? entry.definition.output : undefined;
+      tools[mountable.name] = tool({
+        description: mountable.method.desc,
+        inputSchema,
+        ...output && { outputSchema: output },
+        execute
+      });
+    }
+  }
+  return tools;
+}
+
+// src/tools/manifest.ts
+function utf8Length(value) {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function describeToolCatalog(config) {
+  const deferred = new Set(config.deferredNames ?? []);
+  const entries = collectToolSurface({
+    surface: config,
+    transport: config.transport,
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  }).map(({ kind, service, action, mountable }) => {
+    const schemaBytes = utf8Length(mountable.presentationSchema);
+    return {
+      name: mountable.name,
+      description: mountable.method.desc,
+      inputSchema: mountable.presentationSchema,
+      source: { kind, service, action },
+      schemaBytes,
+      deferred: deferred.has(mountable.name)
+    };
+  });
+  if (config.maxSchemaBytes !== undefined) {
+    const total = entries.reduce((sum, entry) => sum + entry.schemaBytes, 0);
+    if (total > config.maxSchemaBytes) {
+      throw new TypeError(`Tool catalog schemas use ${total} bytes, exceeding maxSchemaBytes ${config.maxSchemaBytes}`);
+    }
+  }
+  return entries;
+}
+function buildToolManifest(config) {
+  return collectToolSurface({
+    surface: config,
+    transport: config.transport,
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  }).map(({ mountable }) => ({
+    name: mountable.name,
+    description: mountable.method.desc,
+    inputSchema: mountable.presentationSchema
+  }));
+}
+
+export { mountAgent, describeToolCatalog, buildToolManifest };

package/dist/index-8p52kd5p.js

@@ -0,0 +1,242 @@
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/internal/exclusive-lock.ts
+import { constants } from "node:fs";
+import { lstat, open, unlink } from "node:fs/promises";
+import { hostname } from "node:os";
+
+// src/internal/process-identity.ts
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+var detectedIdentity;
+async function firstReadableLine(paths) {
+  for (const path of paths) {
+    try {
+      const text = (await readFile(path, "utf8")).trim();
+      if (text.length > 0)
+        return text;
+    } catch {}
+  }
+  return null;
+}
+var run = promisify(execFile);
+function parsePlatformUuid(dump) {
+  return /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(dump)?.[1] ?? null;
+}
+async function readDarwinPlatformUuid(command = "ioreg") {
+  try {
+    const { stdout } = await run(command, ["-rd1", "-c", "IOPlatformExpertDevice"], {
+      timeout: 2000,
+      maxBuffer: 1 << 20,
+      encoding: "utf8"
+    });
+    return parsePlatformUuid(stdout);
+  } catch {
+    return null;
+  }
+}
+async function machineIdentity(declared) {
+  if (declared !== undefined)
+    return declared;
+  if (detectedIdentity !== undefined)
+    return detectedIdentity;
+  detectedIdentity = platform() === "darwin" ? await readDarwinPlatformUuid() : await firstReadableLine(["/etc/machine-id", "/var/lib/dbus/machine-id"]);
+  return detectedIdentity;
+}
+async function probeLiveness(pid) {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return isRecord(error) && error.code === "ESRCH" ? "gone" : "alive";
+  }
+  return await isZombieProcess(pid) ? "gone" : "alive";
+}
+async function isZombieProcess(pid, seam = {}) {
+  const { procRoot = "/proc", psCommand = "ps" } = seam;
+  try {
+    const stat = await readFile(`${procRoot}/${pid}/stat`, "utf8");
+    return stat.slice(stat.lastIndexOf(")") + 1).trimStart().startsWith("Z");
+  } catch {}
+  try {
+    const { stdout } = await run(psCommand, ["-o", "state=", "-p", String(pid)], {
+      timeout: 2000,
+      maxBuffer: 1 << 16,
+      encoding: "utf8"
+    });
+    return stdout.trim().startsWith("Z");
+  } catch {
+    return false;
+  }
+}
+
+// src/internal/exclusive-lock.ts
+function isCode(error, code) {
+  return isRecord(error) && error.code === code;
+}
+function readOwner(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return;
+  }
+  if (!isRecord(parsed))
+    return;
+  const { pid, host, acquiredAt, machine } = parsed;
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0)
+    return;
+  if (typeof host !== "string" || host.length === 0)
+    return;
+  if (typeof acquiredAt !== "string")
+    return;
+  const identified = typeof machine === "string" && machine.length > 0 ? { machine } : {};
+  return { pid, host, acquiredAt, ...identified };
+}
+function attribute(owner, identity) {
+  if (identity !== null && owner.machine !== undefined) {
+    return owner.machine === identity ? "this-machine" : "another-machine";
+  }
+  return owner.host === hostname() ? "this-machine" : "unattributable";
+}
+async function diagnose(owner, declaredIdentity) {
+  if (!owner)
+    return { attribution: "unattributable", liveness: "not-probed", owner: null };
+  const attribution = attribute(owner, await machineIdentity(declaredIdentity));
+  if (attribution !== "this-machine")
+    return { attribution, liveness: "not-probed", owner };
+  return { attribution, liveness: await probeLiveness(owner.pid), owner };
+}
+async function readLockFile(path) {
+  let handle;
+  try {
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    return {
+      owner: readOwner(await handle.readFile("utf8")),
+      ino: info.ino,
+      mtimeMs: info.mtimeMs
+    };
+  } catch {
+    return;
+  } finally {
+    await handle?.close().catch(() => {
+      return;
+    });
+  }
+}
+async function unlinkIfSame(path, ino) {
+  try {
+    if ((await lstat(path)).ino !== ino)
+      return;
+    await unlink(path);
+  } catch (error) {
+    if (!isCode(error, "ENOENT"))
+      throw error;
+  }
+}
+async function createOwned(path, options, reclaimed) {
+  const identity = await machineIdentity(options.machineIdentity);
+  const handle = await open(path, "wx", options.mode);
+  const owner = {
+    pid: process.pid,
+    host: hostname(),
+    acquiredAt: new Date().toISOString(),
+    ...identity !== null && { machine: identity }
+  };
+  let ino;
+  try {
+    await handle.writeFile(`${JSON.stringify(owner)}
+`, "utf8");
+    ino = (await handle.stat()).ino;
+  } catch (error) {
+    await handle.close().catch(() => {
+      return;
+    });
+    await unlink(path).catch(() => {
+      return;
+    });
+    throw error;
+  }
+  let released = false;
+  return {
+    path,
+    owner,
+    reclaimed,
+    async release() {
+      if (released)
+        return;
+      released = true;
+      try {
+        await handle.close();
+      } finally {
+        await unlinkIfSame(path, ino);
+      }
+    }
+  };
+}
+function reclaimable(state, diagnosis, graceMs) {
+  if (state.owner)
+    return diagnosis.liveness === "gone";
+  return graceMs !== undefined && Date.now() - state.mtimeMs >= graceMs;
+}
+async function reclaimUnderGuard(path, options) {
+  const guardPath = `${path}.reclaim`;
+  let guard;
+  try {
+    guard = await createOwned(guardPath, options, false);
+  } catch (error) {
+    if (!isCode(error, "EEXIST"))
+      throw error;
+    const stale = await readLockFile(guardPath);
+    if (stale) {
+      const verdict = await diagnose(stale.owner, options.machineIdentity);
+      if (reclaimable(stale, verdict, options.ownerlessGraceMs ?? 5000)) {
+        await unlinkIfSame(guardPath, stale.ino);
+      }
+    }
+    return;
+  }
+  try {
+    const state = await readLockFile(path);
+    if (state) {
+      const diagnosis = await diagnose(state.owner, options.machineIdentity);
+      if (!reclaimable(state, diagnosis, options.ownerlessGraceMs))
+        return "refused";
+      await unlinkIfSame(path, state.ino);
+    }
+    return await createOwned(path, options, state !== undefined).catch((error) => {
+      if (isCode(error, "EEXIST"))
+        return "refused";
+      throw error;
+    });
+  } finally {
+    await guard.release().catch(() => {
+      return;
+    });
+  }
+}
+async function attemptExclusiveLock(path, options) {
+  try {
+    return { held: await createOwned(path, options, false) };
+  } catch (error) {
+    if (!isCode(error, "EEXIST"))
+      throw error;
+    if (!options.reclaim)
+      return { error };
+    const state = await readLockFile(path);
+    const diagnosis = await diagnose(state?.owner, options.machineIdentity);
+    if (!state || !reclaimable(state, diagnosis, options.ownerlessGraceMs)) {
+      return { error, diagnosis };
+    }
+    const reclaimed = await reclaimUnderGuard(path, options);
+    if (reclaimed !== undefined && reclaimed !== "refused")
+      return { held: reclaimed };
+    return { error, diagnosis };
+  }
+}
+
+export { attemptExclusiveLock };