@scarn/sdk 0.0.0-stage → 0.8.0

package/dist/chunk-gds7w7zh.js

@@ -0,0 +1,330 @@
+// @bun
+import {
+  envVarsSchema
+} from "./chunk-5zsavw98.js";
+import {
+  devcontainerConfigPathSchema
+} from "./chunk-4ggr8af6.js";
+import {
+  MANAGED_RUNTIME_IDS,
+  isManagedRuntimeId
+} from "./chunk-k4y5qt4y.js";
+import {
+  repoConfigInputSchema,
+  repoRuntimeMismatch
+} from "./chunk-cdanncng.js";
+import {
+  findArtifactMarkers
+} from "./chunk-ngy1fdcx.js";
+import {
+  EMBEDDABLE_ARTIFACT_EXTENSIONS,
+  artifactPlatforms,
+  findArtifactFields
+} from "./chunk-y2pv8d6a.js";
+
+// src/definitions/validation/validate-artifacts.ts
+function checkArtifactFields(steps) {
+  const issues = [];
+  for (const step of steps) {
+    for (const field of findArtifactFields(step.resultSchemaJson ?? null)) {
+      if (!field.inArray)
+        continue;
+      issues.push({
+        check: "artifact-field",
+        severity: "error",
+        message: `Step "${step.key}" declares artifact field "${field.path}" inside an ` + `array. Artifact fields in arrays aren't supported; declare a fixed ` + `number of named artifact fields instead.`
+      });
+    }
+  }
+  return issues;
+}
+
+// src/definitions/validation/validation-issue.ts
+function listPaths(paths, limit = 24) {
+  if (paths.length === 0)
+    return "";
+  if (paths.length <= limit)
+    return paths.join(", ");
+  return `${paths.slice(0, limit).join(", ")}, \u2026 (${String(paths.length - limit)} more)`;
+}
+
+// src/definitions/validation/validate-artifact-markers.ts
+var isPlaceholder = (key) => /^<[^<>]*>$/.test(key);
+function stepMarkers(step) {
+  if (!step.prompt)
+    return [];
+  return findArtifactMarkers(step.prompt).flatMap((marker) => marker.ref.type === "signal" && !isPlaceholder(marker.ref.stepKey) && !isPlaceholder(marker.ref.signalKey) ? [
+    {
+      kind: marker.kind,
+      stepKey: marker.ref.stepKey,
+      resultPath: marker.ref.signalKey
+    }
+  ] : []);
+}
+var markerLabel = (marker) => `${marker.kind === "embed" ? "Artifact.embed" : "Artifact.link"}(` + `"signal/${marker.stepKey}/${marker.resultPath}")`;
+function checkMarkerTargets(steps, stepsByKey) {
+  const issues = [];
+  const embeddable = new Set(artifactPlatforms.flatMap((platform) => [
+    ...EMBEDDABLE_ARTIFACT_EXTENSIONS[platform]
+  ]));
+  for (const step of steps) {
+    for (const marker of stepMarkers(step)) {
+      const targets = stepsByKey.get(marker.stepKey);
+      if (!targets)
+        continue;
+      const where = `Step "${step.key}" uses ${markerLabel(marker)}`;
+      for (const target of targets) {
+        if (!target.resultSchemaJson)
+          continue;
+        const fields = findArtifactFields(target.resultSchemaJson);
+        const field = fields.find((candidate) => candidate.path === marker.resultPath);
+        if (!field) {
+          const declared = fields.map((candidate) => candidate.path);
+          issues.push({
+            check: "artifact-marker",
+            severity: "error",
+            message: `${where}, but step "${target.key}" has no artifact field at ` + `"${marker.resultPath}". Artifact fields on "${target.key}": ` + `${declared.length > 0 ? listPaths(declared) : "(none)"}.`
+          });
+          continue;
+        }
+        if (marker.kind !== "embed")
+          continue;
+        const { accept } = field;
+        if (accept.length === 0)
+          continue;
+        if (accept.some((extension) => embeddable.has(extension)))
+          continue;
+        issues.push({
+          check: "artifact-marker",
+          severity: "warning",
+          message: `${where}, but the field accepts only ${accept.join(", ")}, which ` + `no platform can embed, so it will always be linked. Embeddable ` + `extensions: ${[...embeddable].join(", ")}.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function checkArtifactMarkers(steps, stepsByKey) {
+  return checkMarkerTargets(steps, stepsByKey);
+}
+
+// src/definitions/validation/validate-env.ts
+function checkEnv(steps) {
+  const issues = [];
+  for (const step of steps) {
+    if (!step.envJson)
+      continue;
+    issues.push(...checkEnvMcpOwners(step));
+    issues.push(...checkEnvApplies(step));
+    const result = envVarsSchema.safeParse(step.envJson);
+    if (result.success)
+      continue;
+    for (const issue of result.error.issues) {
+      const [index, ...field] = issue.path;
+      const entry = typeof index === "number" ? step.envJson[index] : undefined;
+      const where = typeof index === "number" && entry ? `Step "${step.key}" env var #${String(index + 1)} ("${entry.name}")` : `Step "${step.key}" env`;
+      const fieldLabel = field.length > 0 ? ` ${field.map(String).join(".")}` : "";
+      issues.push({
+        check: "env-var",
+        severity: "error",
+        message: `${where}${fieldLabel}: ${issue.message}`
+      });
+    }
+  }
+  return issues;
+}
+function checkEnvMcpOwners(step) {
+  const serverKeys = Object.keys(step.opencodeMcpJson ?? {}).sort();
+  const serverKeySet = new Set(serverKeys);
+  const issues = [];
+  (step.envJson ?? []).forEach((entry, index) => {
+    if (entry.source !== "inherit" || entry.mcp === undefined)
+      return;
+    if (serverKeySet.has(entry.mcp))
+      return;
+    issues.push({
+      check: "env-var-mcp",
+      severity: "error",
+      message: `Step "${step.key}" env var #${String(index + 1)} ("${entry.name}") ` + `belongs to MCP server "${entry.mcp}", but the step declares no MCP ` + `server with that key. Declared servers: ` + `${serverKeys.length > 0 ? listPaths(serverKeys) : "(none)"}.`
+    });
+  });
+  return issues;
+}
+function checkEnvApplies(step) {
+  const issues = [];
+  (step.envJson ?? []).forEach((entry, index) => {
+    const applies = entry.applies ?? "agent";
+    if (applies === "agent")
+      return;
+    const where = `Step "${step.key}" env var #${String(index + 1)} ("${entry.name}") applies "${applies}"`;
+    if (step.executionMode === "no_workspace") {
+      issues.push({
+        check: "env-var-applies",
+        severity: "error",
+        message: `${where}: setup variables reach devcontainer up, but the step runs on the host (executionMode "no_workspace") with no container to set up. Use applies "agent" or Runtime.devcontainer().`
+      });
+    }
+    if (entry.source === "inherit" && entry.mcp !== undefined) {
+      issues.push({
+        check: "env-var-applies",
+        severity: "error",
+        message: `${where}: it belongs to MCP server "${entry.mcp}", and MCP servers run inside the agent. Use applies "agent".`
+      });
+    }
+  });
+  return issues;
+}
+
+// src/definitions/validation/validate-repo.ts
+function checkRepo(steps) {
+  const issues = [];
+  for (const step of steps) {
+    if (!step.repo)
+      continue;
+    const where = `Step "${step.key}" repo`;
+    const parsed = repoConfigInputSchema.safeParse(step.repo);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        const field = issue.path.map(String).join(".");
+        issues.push({
+          check: "repo",
+          severity: "error",
+          message: `${where}${field ? ` ${field}` : ""}: ${issue.message}`
+        });
+      }
+      continue;
+    }
+    const executionMode = step.executionMode ?? "workspace";
+    const mismatch = repoRuntimeMismatch(executionMode, parsed.data.mode);
+    if (mismatch === null)
+      continue;
+    issues.push({
+      check: "repo",
+      severity: "error",
+      message: `${where} "${parsed.data.mode}" cannot be used with executionMode "${executionMode}": ${mismatch}.`
+    });
+  }
+  return issues;
+}
+
+// src/definitions/validation/validate-runtime.ts
+function checkRuntime(steps) {
+  const issues = [];
+  for (const step of steps) {
+    if (step.kind === "code" && step.executionMode === "no_workspace") {
+      issues.push({
+        check: "runtime",
+        severity: "error",
+        message: `Step "${step.key}": code steps run repo code and need a workspace, so Runtime.host() (executionMode "no_workspace") is not supported for codeStep. Use Runtime.managed.<id>() or Runtime.devcontainer(), or drop the runtime.`
+      });
+    }
+    issues.push(...checkManagedRuntime(step));
+    if (step.devcontainerConfigPath == null)
+      continue;
+    const where = `Step "${step.key}" devcontainerConfigPath "${step.devcontainerConfigPath}"`;
+    if (step.executionMode === "no_workspace") {
+      issues.push({
+        check: "runtime",
+        severity: "error",
+        message: `${where}: a devcontainer config needs a workspace, but the step runs on the host (executionMode "no_workspace"). Use Runtime.devcontainer({ config }) or drop the config.`
+      });
+    }
+    const result = devcontainerConfigPathSchema.safeParse(step.devcontainerConfigPath);
+    if (result.success)
+      continue;
+    for (const issue of result.error.issues) {
+      issues.push({
+        check: "runtime",
+        severity: "error",
+        message: `${where}: ${issue.message}`
+      });
+    }
+  }
+  return issues;
+}
+function checkManagedRuntime(step) {
+  if (step.managedRuntime == null)
+    return [];
+  const where = `Step "${step.key}" managedRuntime "${step.managedRuntime}"`;
+  const problems = [];
+  if (!isManagedRuntimeId(step.managedRuntime)) {
+    problems.push(`unknown managed runtime; expected one of ${MANAGED_RUNTIME_IDS.join(", ")}`);
+  }
+  if (step.kind !== "code") {
+    problems.push("managed runtimes are only supported for code steps. Use Runtime.devcontainer() or Runtime.host() for defineStep");
+  }
+  if (step.executionMode === "no_workspace") {
+    problems.push('a managed runtime needs a workspace, but the step runs on the host (executionMode "no_workspace")');
+  }
+  if (step.devcontainerConfigPath != null) {
+    problems.push("cannot be combined with devcontainerConfigPath. Use either Runtime.managed.<id>() or Runtime.devcontainer({ config })");
+  }
+  return problems.map((problem) => ({
+    check: "runtime",
+    severity: "error",
+    message: `${where}: ${problem}.`
+  }));
+}
+
+// src/definitions/validation/validate-definition-specs.ts
+function checkHealthChecks(steps) {
+  const issues = [];
+  for (const step of steps) {
+    const checks = step.healthChecksJson ?? [];
+    if (checks.length === 0)
+      continue;
+    const mcpServerKeys = Object.keys(step.opencodeMcpJson ?? {});
+    const mcpServerKeySet = new Set(mcpServerKeys);
+    checks.forEach((check, index) => {
+      if (check.kind === "cli")
+        return;
+      const label = check.name ?? check.tool;
+      const where = `Step "${step.key}" health check #${String(index + 1)} ("${label}")`;
+      if (!check.mcp)
+        return;
+      if (!mcpServerKeySet.has(check.mcp)) {
+        issues.push({
+          check: "health-check-mcp-server",
+          severity: "error",
+          message: `${where} names MCP server "${check.mcp}", but the step declares no ` + `such server in mcps. Declared servers: ${mcpServerKeys.length > 0 ? listPaths([...mcpServerKeys].sort()) : "(none)"}.`
+        });
+      }
+      const prefix = `${check.mcp}_`;
+      if (check.tool.startsWith(prefix)) {
+        issues.push({
+          check: "health-check-double-qualified",
+          severity: "error",
+          message: `${where} sets mcp "${check.mcp}" and tool "${check.tool}", which already ` + `starts with "${prefix}". When "mcp" is set, "tool" should be the bare tool ` + `name \u2014 OpenCode resolves it to "${prefix}${check.tool}". Did you mean ` + `tool: "${check.tool.slice(prefix.length)}"?`
+        });
+      }
+    });
+  }
+  return issues;
+}
+function validateDefinitionSpecs(steps) {
+  const stepsByKey = new Map;
+  for (const step of steps) {
+    const existing = stepsByKey.get(step.key);
+    if (existing)
+      existing.push(step);
+    else
+      stepsByKey.set(step.key, [step]);
+  }
+  return [
+    ...checkArtifactFields(steps),
+    ...checkArtifactMarkers(steps, stepsByKey),
+    ...checkHealthChecks(steps),
+    ...checkEnv(steps),
+    ...checkRuntime(steps),
+    ...checkRepo(steps)
+  ];
+}
+function assertValidDefinitionSpecs(steps) {
+  const issues = validateDefinitionSpecs(steps).filter((issue) => issue.severity === "error");
+  if (issues.length === 0)
+    return;
+  const header = issues.length === 1 ? "Definition validation failed:" : `Definition validation failed with ${String(issues.length)} problems:`;
+  throw new Error([header, ...issues.map((issue) => `  \u2022 ${issue.message}`)].join(`
+`));
+}
+export { listPaths, validateDefinitionSpecs, assertValidDefinitionSpecs };

package/dist/chunk-k4y5qt4y.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  exports_external
+} from "./chunk-skzxcba3.js";
+
+// src/managed-runtimes.ts
+var MANAGED_RUNTIME_IDS = ["bun1", "node24"];
+var DEFAULT_CODE_STEP_RUNTIME_ID = "bun1";
+var managedRuntimeIdSchema = exports_external.enum(MANAGED_RUNTIME_IDS);
+function isManagedRuntimeId(value) {
+  return MANAGED_RUNTIME_IDS.includes(value);
+}
+
+export { MANAGED_RUNTIME_IDS, DEFAULT_CODE_STEP_RUNTIME_ID, managedRuntimeIdSchema, isManagedRuntimeId };

package/dist/chunk-mz53r914.js

@@ -0,0 +1,300 @@
+// @bun
+// src/pipelines/source.ts
+var FRAME = /\(?((?:file:\/\/)?[^\s()]+):(\d+):(\d+)\)?\s*$/;
+function sdkRoot() {
+  const here = new URL(import.meta.url).pathname;
+  const parts = here.split("/");
+  return parts.slice(0, -2).join("/") + "/";
+}
+var SDK_ROOT = sdkRoot();
+function toPath(file) {
+  return file.startsWith("file://") ? new URL(file).pathname : file;
+}
+function parseFrame(frame) {
+  const match = FRAME.exec(frame.trim());
+  if (match === null) {
+    return null;
+  }
+  const [, file, line, column] = match;
+  if (file === undefined || line === undefined || column === undefined) {
+    return null;
+  }
+  return { file: toPath(file), line: Number(line), column: Number(column) };
+}
+function captureSite(stack = new Error().stack) {
+  for (const frame of (stack ?? "").split(`
+`).slice(1)) {
+    const site = parseFrame(frame);
+    if (site !== null && !site.file.startsWith(SDK_ROOT) && !site.file.startsWith("node:") && site.file.includes("/")) {
+      return site;
+    }
+  }
+  return null;
+}
+function cwd() {
+  const proc = globalThis.process;
+  return typeof proc?.cwd === "function" ? proc.cwd() : null;
+}
+function formatSite(site) {
+  if (site === null) {
+    return "<unknown>";
+  }
+  const base = cwd();
+  const file = base !== null && site.file.startsWith(`${base}/`) ? site.file.slice(base.length + 1) : site.file;
+  return `${file}:${String(site.line)}`;
+}
+
+// src/pipelines/errors.ts
+function formatIssue(issue) {
+  return `${formatSite(issue.site)} (${issue.pointer === "" ? "/" : issue.pointer}): ${issue.message}`;
+}
+
+class PipelineBuildError extends Error {
+  issues;
+  constructor(key, issues) {
+    super(`Pipeline "${key}" has ${String(issues.length)} build error${issues.length === 1 ? "" : "s"}:
+${issues.map((issue) => `  ${formatIssue(issue)}`).join(`
+`)}`);
+    this.name = "PipelineBuildError";
+    this.issues = issues;
+  }
+}
+
+class AuthoringError extends Error {
+  site;
+  constructor(message, site = captureSite()) {
+    super(message);
+    this.name = "AuthoringError";
+    this.site = site;
+  }
+}
+
+// src/pipelines/registry.ts
+var nodes = new WeakMap;
+var targets = new WeakMap;
+var eaches = new WeakMap;
+var chains = new WeakMap;
+var pendingChains = new Set;
+function registerNode(value, node) {
+  nodes.set(value, node);
+  return value;
+}
+function registerTarget(value, target) {
+  targets.set(value, target);
+  return value;
+}
+function registerEach(value, each) {
+  eaches.set(value, each);
+  return value;
+}
+function registerChain(value, chain) {
+  chains.set(value, chain);
+  if (chain.next !== undefined) {
+    pendingChains.add(chain);
+  }
+  return value;
+}
+function isObject(value) {
+  return (typeof value === "object" || typeof value === "function") && value !== null;
+}
+function nodeOf(value) {
+  return isObject(value) ? nodes.get(value) : undefined;
+}
+function targetOf(value) {
+  return isObject(value) ? targets.get(value) : undefined;
+}
+function eachOf(value) {
+  return isObject(value) ? eaches.get(value) : undefined;
+}
+function chainOf(value) {
+  return isObject(value) ? chains.get(value) : undefined;
+}
+function requireNode(value, what) {
+  const node = nodeOf(value);
+  if (node === undefined) {
+    throw new AuthoringError(`${what} must be a step, decision or reply handle`);
+  }
+  return node;
+}
+
+// src/pipelines/model.ts
+function emptyChain(node) {
+  return {
+    node,
+    settings: {},
+    retry: [],
+    catch: [],
+    next: undefined,
+    site: captureSite()
+  };
+}
+
+// src/pipelines/chain.ts
+function next(data, change) {
+  return chainValue({ ...data, ...change, site: captureSite() });
+}
+function assertOpen(data, method) {
+  if (data.next !== undefined) {
+    throw new AuthoringError(`.${method}() can't follow .next(): the chain for "${data.node.id}" is already finished`);
+  }
+}
+function isTargetSpec(value) {
+  return typeof value === "function" || nodeOf(value) !== undefined || targetOf(value) !== undefined || eachOf(value) !== undefined || chainOf(value) !== undefined;
+}
+function nextData(id, arg) {
+  const site = captureSite();
+  if (isTargetSpec(arg) || !("routes" in arg)) {
+    return {
+      match: undefined,
+      routes: [{ when: undefined, target: arg }],
+      otherwise: undefined,
+      site
+    };
+  }
+  const options = arg;
+  if (options.match !== undefined && options.match !== "first" && options.match !== "all") {
+    throw new AuthoringError(`.next() for "${id}": match "${options.match}" isn't supported; use "first" or "all"`);
+  }
+  if (options.routes === undefined || options.routes.length === 0) {
+    throw new AuthoringError(`.next() for "${id}" needs at least one route in "routes"`);
+  }
+  const routes = options.routes.map((route, index) => {
+    if (route.to === undefined) {
+      throw new AuthoringError(`.next() for "${id}": route ${String(index)} has no "to"`);
+    }
+    return { when: route.when, target: route.to };
+  });
+  return {
+    match: options.match === "all" ? "all" : undefined,
+    routes,
+    otherwise: options.otherwise,
+    site
+  };
+}
+function chainMethods(data) {
+  return {
+    settings: (settings) => {
+      const current = data();
+      assertOpen(current, "settings");
+      return next(current, { settings: { ...settings } });
+    },
+    retry: (options) => {
+      const current = data();
+      assertOpen(current, "retry");
+      if (current.node.kind !== "step") {
+        throw new AuthoringError(`"${current.node.id}" is a wait and can't retry`);
+      }
+      return next(current, {
+        retry: [
+          ...current.retry,
+          { on: [...options.on], maxAttempts: options.maxAttempts }
+        ]
+      });
+    },
+    catch: (on, target) => {
+      const current = data();
+      assertOpen(current, "catch");
+      return next(current, {
+        catch: [...current.catch, { on: [...on], target, site: captureSite() }]
+      });
+    },
+    next: (arg) => {
+      const current = data();
+      assertOpen(current, "next");
+      return next(current, { next: nextData(current.node.id, arg) });
+    }
+  };
+}
+function chainValue(data) {
+  return registerChain(Object.freeze({
+    _tag: "pipeline_chain",
+    node: data.node.id,
+    ...chainMethods(() => data)
+  }), data);
+}
+var HANDLE_METHODS = ["settings", "retry", "catch", "next"];
+function attachChainMethods(handle, node) {
+  const methods = chainMethods(() => emptyChain(node));
+  for (const name of HANDLE_METHODS) {
+    if (node.kind !== "step" && name === "retry") {
+      continue;
+    }
+    Object.defineProperty(handle, name, {
+      value: methods[name],
+      enumerable: false,
+      configurable: true
+    });
+  }
+}
+
+// src/pipelines/handles.ts
+function checkArgs(node, args) {
+  if (args !== undefined && (typeof args !== "object" || args === null)) {
+    throw new AuthoringError(`args for "${node.id}" must be an object`);
+  }
+}
+function targetFn(node) {
+  return (args) => {
+    checkArgs(node, args);
+    return registerTarget(Object.freeze({ _tag: "pipeline_target", to: node.id }), { node, args, site: captureSite() });
+  };
+}
+function partialFn(node) {
+  return (args) => {
+    checkArgs(node, args);
+    return registerTarget(Object.freeze({ _tag: "pipeline_partial", to: node.id }), { node, args, site: captureSite(), partial: true });
+  };
+}
+function makeHandle(handle, node) {
+  attachChainMethods(handle, node);
+  registerNode(handle, node);
+  Object.defineProperty(handle, "partial", {
+    value: partialFn(node),
+    enumerable: false,
+    configurable: true
+  });
+  if (node.kind === "step") {
+    Object.defineProperty(handle, "as", {
+      value: (id) => stepHandleFor({ ...node, id, site: captureSite() }),
+      enumerable: false,
+      configurable: true
+    });
+  }
+  return handle;
+}
+function stepHandleFor(node) {
+  const handle = targetFn(node);
+  if (node.kind === "step") {
+    Object.defineProperties(handle, {
+      key: { value: node.step, enumerable: true },
+      inputSchemaJson: { value: node.inputSchema, enumerable: true },
+      resultSchemaJson: { value: node.resultSchema, enumerable: true },
+      errors: { value: node.errors, enumerable: true }
+    });
+  }
+  return makeHandle(handle, node);
+}
+function stepNode(source, local = true) {
+  return {
+    kind: "step",
+    id: source.key,
+    step: source.key,
+    local,
+    inputSchema: source.inputSchemaJson ?? null,
+    resultSchema: source.resultSchemaJson ?? null,
+    conversation: local && source.kind !== "code" && source.resultSchemaJson === null,
+    errors: [...source.errors ?? []],
+    site: captureSite()
+  };
+}
+function stepCall(node) {
+  return targetFn(node);
+}
+function waitHandle(node) {
+  return makeHandle(targetFn(node), node);
+}
+function bareStepHandle(source, local) {
+  return stepHandleFor(stepNode(source, local));
+}
+
+export { captureSite, formatIssue, PipelineBuildError, AuthoringError, pendingChains, registerNode, registerTarget, registerEach, nodeOf, targetOf, eachOf, chainOf, requireNode, makeHandle, stepNode, stepCall, waitHandle, bareStepHandle };

package/dist/chunk-ngy1fdcx.js

@@ -0,0 +1,57 @@
+// @bun
+// src/contracts/artifact-markers.ts
+var ARTIFACT_MARKER_SCHEME = "artifact:";
+var SIGNAL_REF_PREFIX = "signal/";
+var MARKER_PATTERN = /(!?)\[((?:\\.|[^\\\]\n])*)\]\((?:<artifact:((?:\\.|[^\\<>\n])*)>|artifact:((?:\\.|[^\\()\s])*))\)/g;
+var unescapeMarkerText = (value) => value.replace(/\\(.)/g, "$1");
+var escapeMarkerText = (value) => value.replace(/\s+/g, " ").trim().replace(/[\\[\]]/g, "\\$&");
+var formatMarkerDestination = (rawRef) => {
+  if (/[\s<>]/.test(rawRef)) {
+    if (/[\n\r]/.test(rawRef)) {
+      throw new Error("Artifact marker refs cannot contain line breaks.");
+    }
+    return `<${ARTIFACT_MARKER_SCHEME}${rawRef.replace(/[\\<>]/g, "\\$&")}>`;
+  }
+  return `${ARTIFACT_MARKER_SCHEME}${rawRef.replace(/[\\()]/g, "\\$&")}`;
+};
+function parseArtifactMarkerRef(rawRef) {
+  if (!rawRef.startsWith(SIGNAL_REF_PREFIX)) {
+    return { type: "path", pattern: rawRef };
+  }
+  const rest = rawRef.slice(SIGNAL_REF_PREFIX.length);
+  const slash = rest.indexOf("/");
+  return slash === -1 ? { type: "signal", stepKey: rest, signalKey: "" } : {
+    type: "signal",
+    stepKey: rest.slice(0, slash),
+    signalKey: rest.slice(slash + 1)
+  };
+}
+function formatArtifactMarkerRef(ref) {
+  return ref.type === "signal" ? `${SIGNAL_REF_PREFIX}${ref.stepKey}/${ref.signalKey}` : ref.pattern;
+}
+function buildArtifactMarker(kind, ref, text) {
+  const rawRef = formatArtifactMarkerRef(ref);
+  if (rawRef.length === 0) {
+    throw new Error("Artifact marker refs cannot be empty.");
+  }
+  const bang = kind === "embed" ? "!" : "";
+  return `${bang}[${escapeMarkerText(text)}](${formatMarkerDestination(rawRef)})`;
+}
+function findArtifactMarkers(text) {
+  const matches = [];
+  for (const match of text.matchAll(MARKER_PATTERN)) {
+    const [whole, bang, label, bracketedRef, bareRef] = match;
+    const rawRef = unescapeMarkerText(bracketedRef ?? bareRef ?? "");
+    matches.push({
+      kind: bang === "!" ? "embed" : "link",
+      text: unescapeMarkerText(label ?? ""),
+      rawRef,
+      ref: parseArtifactMarkerRef(rawRef),
+      start: match.index,
+      end: match.index + whole.length
+    });
+  }
+  return matches;
+}
+
+export { ARTIFACT_MARKER_SCHEME, parseArtifactMarkerRef, formatArtifactMarkerRef, buildArtifactMarker, findArtifactMarkers };