@lunora/agent 1.0.0-alpha.1 → 1.0.0-alpha.100

package/dist/sandbox.d.ts

@@ -1,10 +1,11 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BWG0uUtX.js";
+import { b as AgentToolContext, c as AgentToolDefinition } from "./packem_shared/types.d-B8WZl1rU.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
-* The model-provided input to a {@link browserTool} call — a discriminated
-* union on `op` so one tool exposes every headless-browser capability.
-*/
+ * The model-provided input to a {@link browserTool} call — a discriminated
+ * union on `op` so one tool exposes every headless-browser capability.
+ * @experimental
+ */
 type BrowserToolInput = {
   fullPage?: boolean;
   op: "screenshot";
@@ -22,11 +23,12 @@ type BrowserToolInput = {
   url: string;
 };
 /**
-* The model-provided input to a {@link containerTool} call — a discriminated
-* union on `op`. `fetch` sends an HTTP request to the container; `exec` asks it
-* to run a command (routed as a POST to `/exec`, since the container surface
-* exposes no first-class exec RPC — the container app must serve that route).
-*/
+ * The model-provided input to a {@link containerTool} call — a discriminated
+ * union on `op`. `fetch` sends an HTTP request to the container; `exec` asks it
+ * to run a command (delegated to `ctx.containers.<name>.exec`, the first-class
+ * exec contract in `@lunora/container`; the container app serves its route).
+ * @experimental
+ */
 type ContainerToolInput = {
   args?: string[];
   command?: string;
@@ -37,25 +39,29 @@ type ContainerToolInput = {
   op: "fetch";
   path: string;
 };
-/** Author-supplied config for `browserTool`. */
+/**
+ * Author-supplied config for `browserTool`.
+ * @experimental
+ */
 interface BrowserToolOptions {
   /** Override the model-facing description (what the tool does). */
   description?: string;
   /**
-  * Gate a call behind a human approval. Defaults to **unattended** (no gate),
-  * matching the AI SDK. `browserTool` fetches a model-chosen `url` with no
-  * allowlist, so it is an SSRF surface: a prompt-injected model can point it at
-  * an internal/link-local address and read the response back into context. Pass
-  * a boolean or a predicate to gate it (evaluated from replay-stable input, so
-  * keep it deterministic).
-  */
+   * Gate a call behind a human approval. Defaults to **unattended** (no gate),
+   * matching the AI SDK. `browserTool` fetches a model-chosen `url` with no
+   * allowlist, so it is an SSRF surface: a prompt-injected model can point it at
+   * an internal/link-local address and read the response back into context. Pass
+   * a boolean or a predicate to gate it (evaluated from replay-stable input, so
+   * keep it deterministic).
+   */
   needsApproval?: ((input: BrowserToolInput) => boolean) | boolean;
 }
 /**
-* The model-provided input to a {@link fsTool} call — a discriminated union on
-* `op` over an R2-backed virtual filesystem. Paths are relative to the tool's
-* pinned `root`; a `..` that escapes the root is rejected server-side.
-*/
+ * The model-provided input to a {@link fsTool} call — a discriminated union on
+ * `op` over an R2-backed virtual filesystem. Paths are relative to the tool's
+ * pinned `root`; a `..` that escapes the root is rejected server-side.
+ * @experimental
+ */
 type FsToolInput = {
   op: "ls";
   path?: string;
@@ -73,113 +79,127 @@ type FsToolInput = {
   op: "write";
   path: string;
 };
-/** Author-supplied config for `fsTool`. */
+/**
+ * Author-supplied config for `fsTool`.
+ * @experimental
+ */
 interface FsToolOptions {
   /** Override the model-facing description (what the tool does). */
   description?: string;
   /**
-  * Gate a call behind a human approval. Defaults to gating the WRITING ops
-  * (`write`, `rm`) — a prompt-injected model shouldn't silently overwrite or
-  * delete the sandbox — while `ls`/`read`/`stat` run unattended. Pass a boolean
-  * or a predicate (evaluated from replay-stable input, so keep it deterministic).
-  */
+   * Gate a call behind a human approval. Defaults to gating the WRITING ops
+   * (`write`, `rm`) — a prompt-injected model shouldn't silently overwrite or
+   * delete the sandbox — while `ls`/`read`/`stat` run unattended. Pass a boolean
+   * or a predicate (evaluated from replay-stable input, so keep it deterministic).
+   */
   needsApproval?: ((input: FsToolInput) => boolean) | boolean;
   /**
-  * The key prefix every path is scoped under, isolating this tool's files from
-  * the rest of the bucket. Either a fixed string (e.g. `"agents/support"`) or a
-  * function of the tool context — return `` `agents/${ctx.threadKey}` `` (or an
-  * owner-derived prefix) to give each run/user its OWN namespace in a
-  * multi-tenant agent. Default: the bucket root (shared — set a root for
-  * multi-tenant use). The server rejects any `..` that would escape it.
-  */
+   * The key prefix every path is scoped under, isolating this tool's files from
+   * the rest of the bucket. Either a fixed string (e.g. `"agents/support"`) or a
+   * function of the tool context — return `` `agents/${ctx.threadKey}` `` (or an
+   * owner-derived prefix) to give each run/user its OWN namespace in a
+   * multi-tenant agent. Default: the bucket root (shared — set a root for
+   * multi-tenant use). The server rejects any `..` that would escape it.
+   */
   root?: ((context: AgentToolContext) => string) | string;
 }
-/** Author-supplied config for `containerTool`. */
+/**
+ * Author-supplied config for `containerTool`.
+ * @experimental
+ */
 interface ContainerToolOptions {
   /** Override the model-facing description (what the tool does). */
   description?: string;
   /**
-  * Gate a call behind a human approval. Defaults to gating any command
-  * execution: an `exec`, AND a `fetch` whose path resolves to the privileged
-  * `/exec` route (both reach the same command-execution path in the container,
-  * so gating on the `op` name alone would let a `fetch` to `/exec` run a
-  * command unattended). A plain `fetch` to any other route runs unattended.
-  * Pass a boolean or your own predicate to change that. Evaluated from
-  * replay-stable input, so keep it deterministic.
-  */
+   * Gate a call behind a human approval. Defaults to gating any command
+   * execution — an `exec` — plus any `fetch` using a non-idempotent method
+   * (POST/PUT/PATCH/DELETE), so a prompt-injected model cannot reach some
+   * other mutating route unattended. A read-only `fetch` runs unattended. The
+   * exec route itself needs no special case: `@lunora/container` reserves
+   * `/__lunora/*` and refuses a `fetch` into it. Pass a boolean or your own
+   * predicate to change that. Evaluated from replay-stable input, so keep it
+   * deterministic.
+   */
   needsApproval?: ((input: ContainerToolInput) => boolean) | boolean;
 }
 /**
-* A batteries-included agent tool that drives Cloudflare Browser Rendering. One
-* tool exposes every browser op (screenshot / pdf / content / scrape); the model
-* picks via `op`. The call dispatches to the auto-registered `sandbox:invoke`
-* action — which runs on an action ctx carrying `ctx.browser`. Importing the tool
-* makes codegen register the dispatcher and provision the `BROWSER` binding; like
-* any `ctx.browser` user, the app still supplies a `config.browser` thunk
-* (`createBrowser({ binding: env.BROWSER, launch })` with the optional
-* `@cloudflare/playwright` `launch` peer) to `createShardDO()` — codegen never
-* injects that peer, so the browser op throws a directed error until it is wired.
-*
-* Security: the model chooses the `url` with no allowlist, so this is an SSRF
-* surface — pass `opts.needsApproval` to gate calls a prompt-injected model
-* could aim at internal/link-local endpoints.
-*
-* ```ts
-* import { browserTool, defineAgent } from "@lunora/agent/sandbox";
-*
-* export const researcher = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: { browser: browserTool() },
-* });
-* ```
-*/
+ * A batteries-included agent tool that drives Cloudflare Browser Rendering. One
+ * tool exposes every browser op (screenshot / pdf / content / scrape); the model
+ * picks via `op`. The call dispatches to the auto-registered `sandbox:invoke`
+ * action — which runs on an action ctx carrying `ctx.browser`. Importing the tool
+ * makes codegen register the dispatcher and provision the `BROWSER` binding; like
+ * any `ctx.browser` user, the app still supplies a `config.browser` thunk
+ * (`createBrowser({ binding: env.BROWSER, launch })` with the optional
+ * `@cloudflare/playwright` `launch` peer) to `createShardDO()` — codegen never
+ * injects that peer, so the browser op throws a directed error until it is wired.
+ *
+ * Security: the model chooses the `url` with no allowlist, so this is an SSRF
+ * surface — pass `opts.needsApproval` to gate calls a prompt-injected model
+ * could aim at internal/link-local endpoints.
+ *
+ * ```ts
+ * import { browserTool, defineAgent } from "@lunora/agent/sandbox";
+ *
+ * export const researcher = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: { browser: browserTool() },
+ * });
+ * ```
+ * @experimental
+ */
 declare const browserTool: (options?: BrowserToolOptions) => AgentToolDefinition<BrowserToolInput, string>;
 /**
-* A batteries-included agent tool that talks to a declared Cloudflare
-* Container. `name` is the `ctx.containers.&lt;name>` key (the `lunora/containers.ts`
-* export). One tool exposes `fetch` (HTTP request) and `exec` (run a command);
-* the model picks via `op`. The call dispatches to the auto-registered
-* `sandbox:invoke` action, which carries `ctx.containers`.
-*
-* By default a `fetch` runs unattended while command execution is gated behind a
-* human approval — an `exec`, AND a `fetch` whose path resolves to the privileged
-* `/exec` route (both reach the same command-execution path in the container, so
-* gating on the `op` name alone would let a `fetch` to `/exec` run a command
-* unattended). Note a `fetch` can still reach any *other* container route
-* unattended, so scope the container's routes accordingly. Pass
-* `opts.needsApproval` to widen or disable the gate.
-*
-* ```ts
-* import { containerTool, defineAgent } from "@lunora/agent/sandbox";
-*
-* export const ops = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: { sandbox: containerTool("sandbox") },
-* });
-* ```
-*/
+ * A batteries-included agent tool that talks to a declared Cloudflare
+ * Container. `name` is the `ctx.containers.<name>` key (the `lunora/containers.ts`
+ * export). One tool exposes `fetch` (HTTP request) and `exec` (run a command);
+ * the model picks via `op`. The call dispatches to the auto-registered
+ * `sandbox:invoke` action, which carries `ctx.containers`.
+ *
+ * By default a read-only (GET/HEAD/OPTIONS, or method-omitted) `fetch` runs
+ * unattended while everything else is gated behind a human approval — an
+ * `exec`; a `fetch` whose path resolves to the privileged exec route (both
+ * reach the same command-execution path in the container, so gating on the
+ * `op` name alone would let a `fetch` to it run a command unattended);
+ * and a `fetch` using a non-idempotent method (POST/PUT/PATCH/DELETE) to ANY
+ * route, since a prompt-injected model could otherwise mutate container state
+ * through some other privileged route just by avoiding the literal exec
+ * path. A `fetch` can still reach any *other read* route unattended, so scope
+ * the container's GET routes accordingly. Pass `opts.needsApproval` to widen
+ * or disable the gate.
+ *
+ * ```ts
+ * import { containerTool, defineAgent } from "@lunora/agent/sandbox";
+ *
+ * export const ops = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: { sandbox: containerTool("sandbox") },
+ * });
+ * ```
+ * @experimental
+ */
 declare const containerTool: (name: string, options?: ContainerToolOptions) => AgentToolDefinition<ContainerToolInput, string>;
 /**
-* A batteries-included agent tool exposing a persistent, R2-backed virtual
-* filesystem. `bucket` is the R2 binding name; every path is scoped under the
-* pinned `opts.root` (a `..` that would escape it is rejected). One tool exposes
-* `ls`/`read`/`write`/`rm`/`stat`; the model picks via `op`. The call dispatches
-* to the auto-registered `sandbox:invoke` action, which reads the bucket from
-* `ctx.env`. workerd has no real shell — this is object-store-backed file I/O.
-*
-* By default the writing ops (`write`/`rm`) pause for a human approval while
-* reads run unattended; pass `opts.needsApproval` to change that. Importing the
-* tool registers the dispatcher; the app must declare the `r2_bucket` binding in
-* `wrangler.jsonc` (the fs op throws a directed error until it is wired).
-*
-* ```ts
-* import { defineAgent, fsTool } from "@lunora/agent/sandbox";
-*
-* export const coder = defineAgent({
-*     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
-*     tools: { fs: fsTool("SANDBOX_BUCKET", { root: "agents/coder" }) },
-* });
-* ```
-*/
+ * A batteries-included agent tool exposing a persistent, R2-backed virtual
+ * filesystem. `bucket` is the R2 binding name; every path is scoped under the
+ * pinned `opts.root` (a `..` that would escape it is rejected). One tool exposes
+ * `ls`/`read`/`write`/`rm`/`stat`; the model picks via `op`. The call dispatches
+ * to the auto-registered `sandbox:invoke` action, which reads the bucket from
+ * `ctx.env`. workerd has no real shell — this is object-store-backed file I/O.
+ *
+ * By default the writing ops (`write`/`rm`) pause for a human approval while
+ * reads run unattended; pass `opts.needsApproval` to change that. Importing the
+ * tool registers the dispatcher; the app must declare the `r2_bucket` binding in
+ * `wrangler.jsonc` (the fs op throws a directed error until it is wired).
+ *
+ * ```ts
+ * import { defineAgent, fsTool } from "@lunora/agent/sandbox";
+ *
+ * export const coder = defineAgent({
+ *     model: "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
+ *     tools: { fs: fsTool("SANDBOX_BUCKET", { root: "agents/coder" }) },
+ * });
+ * ```
+ * @experimental
+ */
 declare const fsTool: (bucket: string, options?: FsToolOptions) => AgentToolDefinition<FsToolInput>;
 export { type BrowserToolInput, type BrowserToolOptions, type ContainerToolInput, type ContainerToolOptions, type FsToolInput, type FsToolOptions, browserTool, containerTool, fsTool };

package/dist/sandbox.mjs

@@ -1,109 +1 @@
-import { LunoraError } from '@lunora/errors';
-import { jsonSchema } from 'ai';
-import { toFunctionReference, SANDBOX_INVOKE_PATH } from './packem_shared/AGENT_MODULE-Dnt_-AAT.mjs';
-
-const SANDBOX_REF = toFunctionReference(SANDBOX_INVOKE_PATH);
-const DEFAULT_BROWSER_DESCRIPTION = 'Drive a headless browser: screenshot a page, render it to PDF, read its HTML content, or scrape it. Set `op` to "screenshot" | "pdf" | "content" | "scrape" and pass the target `url`.';
-const DEFAULT_CONTAINER_DESCRIPTION = 'Talk to a sandboxed container: `fetch` an HTTP path on it, or `exec` a command inside it. Set `op` to "fetch" (with `path`) or "exec" (with `command`).';
-const DEFAULT_FS_DESCRIPTION = 'Read and write files in a persistent sandbox filesystem. Set `op` to "ls" (list a directory), "read", "write" (with `content`), "rm", or "stat", and pass `path`.';
-const defaultFsGate = (input) => input.op === "write" || input.op === "rm";
-const FS_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    content: { description: "write: the file contents.", type: "string" },
-    op: { description: "The filesystem operation to run.", enum: ["ls", "read", "write", "rm", "stat"], type: "string" },
-    path: { description: "The file or directory path, relative to the sandbox root.", type: "string" }
-  },
-  required: ["op"],
-  type: "object"
-});
-const BROWSER_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    fullPage: { description: "screenshot: capture the full scrollable page rather than just the viewport.", type: "boolean" },
-    op: { description: "The browser operation to run.", enum: ["screenshot", "scrape", "pdf", "content"], type: "string" },
-    selector: { description: "scrape: optional CSS selector hint to narrow the extraction.", type: "string" },
-    type: { description: "screenshot: image encoding (default png).", enum: ["png", "jpeg"], type: "string" },
-    url: { description: "The URL to operate on.", type: "string" }
-  },
-  required: ["op", "url"],
-  type: "object"
-});
-const CONTAINER_EXEC_ROUTE = "/exec";
-const CONTAINER_PATH_QUERY_SPLIT = /[?#]/u;
-const normalizeContainerPath = (path) => {
-  const [raw = ""] = (path ?? "").split(CONTAINER_PATH_QUERY_SPLIT);
-  const segments = [];
-  for (const segment of raw.split("/")) {
-    if (segment === "" || segment === ".") {
-      continue;
-    }
-    if (segment === "..") {
-      segments.pop();
-      continue;
-    }
-    segments.push(segment);
-  }
-  return `/${segments.join("/")}`;
-};
-const defaultContainerGate = (input) => {
-  if (input.op === "exec") {
-    return true;
-  }
-  return normalizeContainerPath(input.path) === CONTAINER_EXEC_ROUTE;
-};
-const CONTAINER_TOOL_SCHEMA = jsonSchema({
-  properties: {
-    args: { description: "exec: command arguments.", items: { type: "string" }, type: "array" },
-    body: { description: "fetch: request body.", type: "string" },
-    command: { description: "exec: the command to run.", type: "string" },
-    method: { description: "fetch: HTTP method (default GET).", type: "string" },
-    op: { description: "The container operation to run.", enum: ["fetch", "exec"], type: "string" },
-    path: { description: "fetch: request path on the container (e.g. /health).", type: "string" }
-  },
-  required: ["op"],
-  type: "object"
-});
-const browserTool = (options = {}) => {
-  return {
-    description: options.description ?? DEFAULT_BROWSER_DESCRIPTION,
-    // Pin `kind` LAST so out-of-schema model input can never override it.
-    execute: (input, context) => context.run(SANDBOX_REF, { ...input, kind: "browser" }),
-    inputSchema: BROWSER_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    ...options.needsApproval === void 0 ? {} : { needsApproval: options.needsApproval }
-  };
-};
-const containerTool = (name, options = {}) => {
-  if (typeof name !== "string" || name.length === 0) {
-    throw new LunoraError("INTERNAL", "@lunora/agent: containerTool requires a container `name` (the ctx.containers.<name> key from lunora/containers.ts)");
-  }
-  const needsApproval = options.needsApproval ?? defaultContainerGate;
-  return {
-    description: options.description ?? DEFAULT_CONTAINER_DESCRIPTION,
-    // Pin `kind`/`name` LAST so out-of-schema model input can never override
-    // the authoritative container the author pinned.
-    execute: (input, context) => context.run(SANDBOX_REF, { ...input, kind: "container", name }),
-    inputSchema: CONTAINER_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    needsApproval
-  };
-};
-const fsTool = (bucket, options = {}) => {
-  if (typeof bucket !== "string" || bucket.length === 0) {
-    throw new LunoraError("INTERNAL", "@lunora/agent: fsTool requires an R2 `bucket` binding name (the r2_bucket declared in wrangler.jsonc)");
-  }
-  return {
-    description: options.description ?? DEFAULT_FS_DESCRIPTION,
-    // Pin kind/bucket/root LAST so out-of-schema model input can never override
-    // the authoritative bucket + sandbox root the author pinned. `root` may be
-    // a function of the ctx (per-run/owner isolation), resolved here.
-    execute: (input, context) => {
-      const root = typeof options.root === "function" ? options.root(context) : options.root ?? "";
-      return context.run(SANDBOX_REF, { ...input, bucket, kind: "fs", root });
-    },
-    inputSchema: FS_TOOL_SCHEMA,
-    isLunoraAgentTool: true,
-    needsApproval: options.needsApproval ?? defaultFsGate
-  };
-};
-
-export { browserTool, containerTool, fsTool };
+import{LunoraError as a}from"@lunora/errors";import{jsonSchema as i}from"ai";import{toFunctionReference as p,SANDBOX_INVOKE_PATH as c}from"./packem_shared/AGENT_MODULE-M4D1EejI.mjs";const s=p(c),d='Drive a headless browser: screenshot a page, render it to PDF, read its HTML content, or scrape it. Set `op` to "screenshot" | "pdf" | "content" | "scrape" and pass the target `url`.',h='Talk to a sandboxed container: `fetch` an HTTP path on it, or `exec` a command inside it. Set `op` to "fetch" (with `path`) or "exec" (with `command`).',l='Read and write files in a persistent sandbox filesystem. Set `op` to "ls" (list a directory), "read", "write" (with `content`), "rm", or "stat", and pass `path`.',u=e=>e.op==="write"||e.op==="rm",T=i({properties:{content:{description:"write: the file contents.",type:"string"},op:{description:"The filesystem operation to run.",enum:["ls","read","write","rm","stat"],type:"string"},path:{description:"The file or directory path, relative to the sandbox root.",type:"string"}},required:["op"],type:"object"}),m=i({properties:{fullPage:{description:"screenshot: capture the full scrollable page rather than just the viewport.",type:"boolean"},op:{description:"The browser operation to run.",enum:["screenshot","scrape","pdf","content"],type:"string"},selector:{description:"scrape: optional CSS selector hint to narrow the extraction.",type:"string"},type:{description:"screenshot: image encoding (default png).",enum:["png","jpeg"],type:"string"},url:{description:"The URL to operate on.",type:"string"}},required:["op","url"],type:"object"}),g=new Set(["DELETE","PATCH","POST","PUT"]),f=e=>e.op==="exec"||g.has((e.method??"GET").toUpperCase()),y=i({properties:{args:{description:"exec: command arguments.",items:{type:"string"},type:"array"},body:{description:"fetch: request body.",type:"string"},command:{description:"exec: the command to run.",type:"string"},method:{description:"fetch: HTTP method (default GET).",type:"string"},op:{description:"The container operation to run.",enum:["fetch","exec"],type:"string"},path:{description:"fetch: request path on the container (e.g. /health).",type:"string"}},required:["op"],type:"object"}),w=(e={})=>({description:e.description??d,execute:(t,r)=>r.run(s,{...t,kind:"browser"}),inputSchema:m,isLunoraAgentTool:!0,...e.needsApproval===void 0?{}:{needsApproval:e.needsApproval}}),O=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new a("INTERNAL","@lunora/agent: containerTool requires a container `name` (the ctx.containers.<name> key from lunora/containers.ts)");const r=t.needsApproval??f;return{description:t.description??h,execute:(o,n)=>n.run(s,{...o,kind:"container",name:e}),inputSchema:y,isLunoraAgentTool:!0,needsApproval:r}},_=(e,t={})=>{if(typeof e!="string"||e.length===0)throw new a("INTERNAL","@lunora/agent: fsTool requires an R2 `bucket` binding name (the r2_bucket declared in wrangler.jsonc)");return{description:t.description??l,execute:(r,o)=>{const n=typeof t.root=="function"?t.root(o):t.root??"";return o.run(s,{...r,bucket:e,kind:"fs",root:n})},inputSchema:T,isLunoraAgentTool:!0,needsApproval:t.needsApproval??u}};export{w as browserTool,O as containerTool,_ as fsTool};

package/dist/skill-markdown.d.mts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, d as SkillDefinition } from "./packem_shared/types.d-B8WZl1rU.mjs";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+ * Declare a skill whose prose lives in a markdown file.
+ *
+ * ```ts
+ * import triage from "./skills/triage/SKILL.md?raw";
+ * import { functionTool } from "@lunora/agent";
+ * import { skillFromMarkdown } from "@lunora/agent/skill-markdown";
+ *
+ * export const triageSkill = skillFromMarkdown(triage, {
+ *     tools: { searchCode: functionTool(api.code.search, { ... }) },
+ * });
+ * ```
+ *
+ * ```md
+ * ---
+ * name: triage
+ * ---
+ * Reproduce the report before proposing a cause. Cite the failing test.
+ * ```
+ *
+ * The split is the point: the instructions are the part a non-author reads,
+ * reviews and copies between projects, so they belong in a file that is legible
+ * on its own — and the `name` travels WITH that file, so a skill can move
+ * without a matching TypeScript wrapper. Tools and `knowledge` stay in code,
+ * because they are code.
+ *
+ * Getting the markdown here is the caller's job (`?raw` under Vite, a build-time
+ * import elsewhere) — a Worker has no filesystem to read it from at runtime, so
+ * this takes the string rather than a path.
+ * @experimental
+ */
+declare const skillFromMarkdown: (markdown: string, extras?: SkillMarkdownExtras) => SkillDefinition;
+export { type SkillMarkdownExtras, skillFromMarkdown };

package/dist/skill-markdown.d.ts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, d as SkillDefinition } from "./packem_shared/types.d-B8WZl1rU.js";
+import '@lunora/mail/inbound';
+import 'ai';
+/**
+ * Declare a skill whose prose lives in a markdown file.
+ *
+ * ```ts
+ * import triage from "./skills/triage/SKILL.md?raw";
+ * import { functionTool } from "@lunora/agent";
+ * import { skillFromMarkdown } from "@lunora/agent/skill-markdown";
+ *
+ * export const triageSkill = skillFromMarkdown(triage, {
+ *     tools: { searchCode: functionTool(api.code.search, { ... }) },
+ * });
+ * ```
+ *
+ * ```md
+ * ---
+ * name: triage
+ * ---
+ * Reproduce the report before proposing a cause. Cite the failing test.
+ * ```
+ *
+ * The split is the point: the instructions are the part a non-author reads,
+ * reviews and copies between projects, so they belong in a file that is legible
+ * on its own — and the `name` travels WITH that file, so a skill can move
+ * without a matching TypeScript wrapper. Tools and `knowledge` stay in code,
+ * because they are code.
+ *
+ * Getting the markdown here is the caller's job (`?raw` under Vite, a build-time
+ * import elsewhere) — a Worker has no filesystem to read it from at runtime, so
+ * this takes the string rather than a path.
+ * @experimental
+ */
+declare const skillFromMarkdown: (markdown: string, extras?: SkillMarkdownExtras) => SkillDefinition;
+export { type SkillMarkdownExtras, skillFromMarkdown };

package/dist/skill-markdown.mjs

@@ -0,0 +1 @@
+import{LunoraError as o}from"@lunora/errors";import{parse as s}from"yaml";import{defineSkill as l}from"./packem_shared/defineSkill-DGGvDWNq.mjs";const m=/^\uFEFF?[ \t]*---[ \t]*\r?\n/u,h=/^---[ \t]*$/mu,c=t=>{const r=m.exec(t);if(!r)return{body:t.trim(),data:{}};const n=t.slice(r[0].length),e=h.exec(n);if(!e)throw new o("INTERNAL","@lunora/agent: the skill markdown opens with `---` but never closes the frontmatter block. Add a closing `---` on its own line.");let a;try{a=s(n.slice(0,e.index))}catch(i){throw new o("INTERNAL",`@lunora/agent: the skill markdown has invalid YAML frontmatter — ${i instanceof Error?i.message:String(i)}`)}return{body:n.slice(e.index+e[0].length).trim(),data:typeof a=="object"&&a!==null?a:{}}},w=(t,r={})=>{if(typeof t!="string")throw new o("INTERNAL",`@lunora/agent: skillFromMarkdown expects the markdown SOURCE as a string, got ${typeof t}`);const{body:n,data:e}=c(t);if(e.name!==void 0&&typeof e.name!="string")throw new o("INTERNAL",`@lunora/agent: the skill markdown's \`name\` must be a string, got ${Array.isArray(e.name)?"array":typeof e.name}. Quote it if the value looks like a number or a boolean (\`name: "2fa"\`).`);if(typeof e.name!="string")throw new o("INTERNAL","@lunora/agent: skillFromMarkdown found no `name` in the markdown frontmatter. Open the file with a `---` line, put `name: <identifier>` on its own line, and close it with `---`. Other keys are parsed and ignored — only `name` is read here.");if(n==="")throw new o("INTERNAL",`@lunora/agent: the skill markdown for "${e.name}" has no body — the instructions below the closing \`---\` are what the skill contributes.`);return l({...r,instructions:n,name:e.name})};export{w as skillFromMarkdown};