@lunora/agent 1.0.0-alpha.40 → 1.0.0-alpha.42

package/dist/channels.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BC_N2z6_.mjs";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BC_N2z6_.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-PMYeuDE7.mjs";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-PMYeuDE7.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/channels.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BC_N2z6_.js";
-export type { I as InboundChannelEvent } from "./packem_shared/types.d-BC_N2z6_.js";
+import { A as AgentDefinition } from "./packem_shared/types.d-PMYeuDE7.js";
+export type { I as InboundChannelEvent } from "./packem_shared/types.d-PMYeuDE7.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/inbound.d.mts

@@ -1,4 +1,4 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BC_N2z6_.mjs";
+import { A as AgentDefinition } from "./packem_shared/types.d-PMYeuDE7.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/inbound.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentDefinition } from "./packem_shared/types.d-BC_N2z6_.js";
+import { A as AgentDefinition } from "./packem_shared/types.d-PMYeuDE7.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-BC_N2z6_.mjs";
-export type { y as AgentApprovalContext, z as AgentEmailMapper, B as AgentEmailRun, C as AgentGenerateOptions, D as AgentGenerateResult, E as AgentInstructionsContext, F as AgentLiveEvent, G as AgentMemoryOptions, H as AgentMemorySource, J as AgentMessageStatus, K as AgentOnStepFinish, L as AgentPrepareStep, M as AgentPrepareStepInput, N as AgentPrepareStepResult, O as AgentProgressEvent, P as AgentRunHandle, Q as AgentStepFinishInfo, R as AgentStepInfo, T as AgentThreadStatus, U as AgentTokenDelta, V as AgentToolCall, a as AgentToolContext, W as AgentUsage, X as AgentVoiceConfig, Y as AgentWorkflowBindingLike, Z as AgentWorkflowInstanceLike } from "./packem_shared/types.d-BC_N2z6_.mjs";
+import { A as AgentDefinition, d as AgentCompact, e as AgentEpisodeExtract, f as AgentGraphExtract, g as AgentGenerate, h as AgentTokenSink, i as AgentRunInput, j as AgentFunctionPaths, k as AgentRunFunction, l as AgentStepLike, m as AgentStreamGenerate, n as AgentRunResult, o as AgentMessageRow, p as AgentConfig, c as SkillDefinition, q as AnyAgentTool, r as AgentAsToolOptions, s as AgentSubToolInput, b as AgentToolDefinition, t as AgentBindingSpec, u as AgentHandle, v as AgentToolConfig, w as AgentFunctionReference, x as AgentModelInput, y as SkillConfig } from "./packem_shared/types.d-PMYeuDE7.mjs";
+export type { z as AgentApprovalContext, B as AgentEmailMapper, C as AgentEmailRun, D as AgentGenerateOptions, E as AgentGenerateResult, F as AgentInstructionsContext, G as AgentLiveEvent, H as AgentMemoryOptions, J as AgentMemorySource, K as AgentMessageStatus, L as AgentOnStepFinish, M as AgentPrepareStep, N as AgentPrepareStepInput, O as AgentPrepareStepResult, P as AgentProgressEvent, Q as AgentRunHandle, R as AgentStepFinishInfo, T as AgentStepInfo, U as AgentThreadStatus, V as AgentTokenDelta, W as AgentToolCall, a as AgentToolContext, X as AgentUsage, Y as AgentVoiceConfig, Z as AgentWorkflowBindingLike, _ as AgentWorkflowInstanceLike } from "./packem_shared/types.d-PMYeuDE7.mjs";
 export { type AgentComponent, agentComponent, agentExtension } from "./component.mjs";
 import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
 export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.mjs";
@@ -183,7 +183,7 @@ declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<
 interface ToolScriptStep {
   /** A stable name later steps reference the output by. */
   id: string;
-  /** The tool's input; values may embed `{ "$from": "&lt;stepId>", "$path": "a.b" }` refs. */
+  /** The tool's input; values may embed `{ "$from": "<stepId>", "$path": "a.b" }` refs. */
   input?: Record<string, unknown>;
   /** The tool to call — one of the tools handed to {@link codeTool}. */
   tool: string;
@@ -821,15 +821,15 @@ declare class VoiceSessionDO {
 }
 /**
  * Compile a `defineAgent` definition into the workflow the generated
- * `&lt;Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
+ * `<Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
  *
  * ```ts
  * import LunoraWorkflow from "@lunora/workflow/do";
  * import { compileAgentWorkflow } from "@lunora/agent";
  * import { support } from "../agents.js";
  *
- * export class SupportAgentWorkflow extends LunoraWorkflow&lt;AgentRunInput, AgentRunResult> {
- *     public constructor(ctx: ConstructorParameters&lt;typeof LunoraWorkflow>[0], env: Record&lt;string, unknown>) {
+ * export class SupportAgentWorkflow extends LunoraWorkflow<AgentRunInput, AgentRunResult> {
+ *     public constructor(ctx: ConstructorParameters<typeof LunoraWorkflow>[0], env: Record<string, unknown>) {
  *         super(ctx, env, compileAgentWorkflow(support, "support"), "support");
  *     }
  * }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentDefinition, c as AgentCompact, d as AgentEpisodeExtract, e as AgentGraphExtract, f as AgentGenerate, g as AgentTokenSink, h as AgentRunInput, i as AgentFunctionPaths, j as AgentRunFunction, k as AgentStepLike, l as AgentStreamGenerate, m as AgentRunResult, n as AgentMessageRow, o as AgentConfig, S as SkillDefinition, p as AnyAgentTool, q as AgentAsToolOptions, r as AgentSubToolInput, b as AgentToolDefinition, s as AgentBindingSpec, t as AgentHandle, u as AgentToolConfig, v as AgentFunctionReference, w as AgentModelInput, x as SkillConfig } from "./packem_shared/types.d-BC_N2z6_.js";
-export type { y as AgentApprovalContext, z as AgentEmailMapper, B as AgentEmailRun, C as AgentGenerateOptions, D as AgentGenerateResult, E as AgentInstructionsContext, F as AgentLiveEvent, G as AgentMemoryOptions, H as AgentMemorySource, J as AgentMessageStatus, K as AgentOnStepFinish, L as AgentPrepareStep, M as AgentPrepareStepInput, N as AgentPrepareStepResult, O as AgentProgressEvent, P as AgentRunHandle, Q as AgentStepFinishInfo, R as AgentStepInfo, T as AgentThreadStatus, U as AgentTokenDelta, V as AgentToolCall, a as AgentToolContext, W as AgentUsage, X as AgentVoiceConfig, Y as AgentWorkflowBindingLike, Z as AgentWorkflowInstanceLike } from "./packem_shared/types.d-BC_N2z6_.js";
+import { A as AgentDefinition, d as AgentCompact, e as AgentEpisodeExtract, f as AgentGraphExtract, g as AgentGenerate, h as AgentTokenSink, i as AgentRunInput, j as AgentFunctionPaths, k as AgentRunFunction, l as AgentStepLike, m as AgentStreamGenerate, n as AgentRunResult, o as AgentMessageRow, p as AgentConfig, c as SkillDefinition, q as AnyAgentTool, r as AgentAsToolOptions, s as AgentSubToolInput, b as AgentToolDefinition, t as AgentBindingSpec, u as AgentHandle, v as AgentToolConfig, w as AgentFunctionReference, x as AgentModelInput, y as SkillConfig } from "./packem_shared/types.d-PMYeuDE7.js";
+export type { z as AgentApprovalContext, B as AgentEmailMapper, C as AgentEmailRun, D as AgentGenerateOptions, E as AgentGenerateResult, F as AgentInstructionsContext, G as AgentLiveEvent, H as AgentMemoryOptions, J as AgentMemorySource, K as AgentMessageStatus, L as AgentOnStepFinish, M as AgentPrepareStep, N as AgentPrepareStepInput, O as AgentPrepareStepResult, P as AgentProgressEvent, Q as AgentRunHandle, R as AgentStepFinishInfo, T as AgentStepInfo, U as AgentThreadStatus, V as AgentTokenDelta, W as AgentToolCall, a as AgentToolContext, X as AgentUsage, Y as AgentVoiceConfig, Z as AgentWorkflowBindingLike, _ as AgentWorkflowInstanceLike } from "./packem_shared/types.d-PMYeuDE7.js";
 export { type AgentComponent, agentComponent, agentExtension } from "./component.js";
 import { FlexibleSchema, LanguageModel, ModelMessage } from 'ai';
 export { agentBindingName, agentClassName, agentDefaultName, voiceBindingName, voiceClassName } from "./naming.js";
@@ -183,7 +183,7 @@ declare const agentAsTool: (options: AgentAsToolOptions) => AgentToolDefinition<
 interface ToolScriptStep {
   /** A stable name later steps reference the output by. */
   id: string;
-  /** The tool's input; values may embed `{ "$from": "&lt;stepId>", "$path": "a.b" }` refs. */
+  /** The tool's input; values may embed `{ "$from": "<stepId>", "$path": "a.b" }` refs. */
   input?: Record<string, unknown>;
   /** The tool to call — one of the tools handed to {@link codeTool}. */
   tool: string;
@@ -821,15 +821,15 @@ declare class VoiceSessionDO {
 }
 /**
  * Compile a `defineAgent` definition into the workflow the generated
- * `&lt;Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
+ * `<Name>AgentWorkflow` entrypoint class runs. Codegen emits, per agent:
  *
  * ```ts
  * import LunoraWorkflow from "@lunora/workflow/do";
  * import { compileAgentWorkflow } from "@lunora/agent";
  * import { support } from "../agents.js";
  *
- * export class SupportAgentWorkflow extends LunoraWorkflow&lt;AgentRunInput, AgentRunResult> {
- *     public constructor(ctx: ConstructorParameters&lt;typeof LunoraWorkflow>[0], env: Record&lt;string, unknown>) {
+ * export class SupportAgentWorkflow extends LunoraWorkflow<AgentRunInput, AgentRunResult> {
+ *     public constructor(ctx: ConstructorParameters<typeof LunoraWorkflow>[0], env: Record<string, unknown>) {
  *         super(ctx, env, compileAgentWorkflow(support, "support"), "support");
  *     }
  * }

package/dist/packem_shared/{types.d-BC_N2z6_.d.mts → types.d-PMYeuDE7.d.mts}

@@ -23,7 +23,7 @@ interface AgentStepLike {
   /**
    * Durably hibernate until an external event of `type` arrives, then return
    * its payload. Used for human-in-the-loop approvals: a run pauses on
-   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
+   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
    * wait is memoized — a replay returns the recorded decision without pausing
    * again. Signature mirrors `@lunora/workflow`'s `WorkflowStepLike`.
    */
@@ -42,7 +42,7 @@ interface AgentStepLike {
  * `idempotencyKey`.
  *
  * The `idempotencyKey` is the deterministic durable-step name
- * (`tool:&lt;name>:&lt;toolCallId>`). A COMPLETED tool step is never re-run on a
+ * (`tool:<name>:<toolCallId>`). A COMPLETED tool step is never re-run on a
  * workflow replay (native step memoization) — but a step that FAILS mid-body
  * is retried at-least-once, so a side-effecting tool (charge a card, send a
  * mail) must dedupe on this key itself.
@@ -138,7 +138,7 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    * Gate the tool behind a human approval (mirrors the AI SDK's
    * `needsApproval`). When it resolves truthy the durable run PAUSES — the
    * thread moves to `"awaiting_input"` and the workflow hibernates on
-   * `approval:&lt;toolCallId>` — until a client calls `agents:agentResolveApproval`.
+   * `approval:<toolCallId>` — until a client calls `agents:agentResolveApproval`.
    * On approve the tool runs exactly as normal; on reject it is skipped and a
    * tool result explaining the rejection is persisted so the next turn recovers.
    * A boolean gates statically; a function gates per input. Default: `false`
@@ -146,7 +146,7 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    *
    * The boolean/`undefined` forms are compile-time constants re-derived
    * identically on every replay — no durable step. The FUNCTION form runs
-   * inside its OWN durable step (`tool:approval-gate:&lt;toolCallId>`, distinct
+   * inside its OWN durable step (`tool:approval-gate:<toolCallId>`, distinct
    * from the tool's own step), so it now runs exactly once per call, not once
    * per replay. It must still be otherwise pure: deterministic given its
    * inputs (no `Date.now()`/`Math.random()`) and free of side effects — the
@@ -269,7 +269,7 @@ interface AgentMemoryOptions {
  * (`key: "default"`) from {@link AgentConfig.memory}, then one per skill that
  * carries `knowledge` (keyed by the skill's name). The key names the durable
  * step — the default source keeps the historic `"memory:retrieve"`, a skill
- * source uses `"memory:retrieve:&lt;key>"` — so replay stays deterministic.
+ * source uses `"memory:retrieve:<key>"` — so replay stays deterministic.
  * @experimental
  */
 interface AgentMemorySource extends AgentMemoryOptions {
@@ -325,7 +325,7 @@ interface SkillConfig {
   knowledge?: AgentMemoryOptions;
   /**
    * The skill's identifier — namespaces this skill's `knowledge` memory source
-   * (the durable step `memory:retrieve:&lt;name>`). Must be identifier-shaped.
+   * (the durable step `memory:retrieve:<name>`). Must be identifier-shaped.
    */
   name: string;
   /**
@@ -335,6 +335,12 @@ interface SkillConfig {
    */
   tools?: Record<string, AnyAgentTool>;
 }
+/**
+ * The code-side parts of a markdown-authored skill — everything `SKILL.md`
+ * cannot carry. `name` and `instructions` come from the file itself.
+ * @experimental
+ */
+type SkillMarkdownExtras = Omit<SkillConfig, "instructions" | "name">;
 /**
  * A `defineSkill` result — config plus the brand the agent merge checks.
  * @experimental
@@ -375,7 +381,7 @@ interface AgentStepFinishInfo {
 }
 /**
  * Called after each LLM turn with that turn's text, tool calls, and usage. Runs
- * inside a named durable step (`agent:step-finish:&lt;turn>`) so it fires exactly
+ * inside a named durable step (`agent:step-finish:<turn>`) so it fires exactly
  * once per turn even across a workflow replay.
  * @experimental
  */
@@ -547,7 +553,7 @@ interface AgentConfig {
   model: AgentModelInput;
   /**
    * Optional override for the deployed workflow name (`wrangler.jsonc`
-   * `workflows[].name`). Defaults to `agent-&lt;kebab-cased export name>`. Does
+   * `workflows[].name`). Defaults to `agent-<kebab-cased export name>`. Does
    * NOT change the binding name, which is always derived from the export
    * name (`support` → `AGENT_SUPPORT`).
    */
@@ -594,7 +600,7 @@ interface AgentConfig {
    * Opt this agent into being STARTED over the public RPC boundary — i.e. via
    * the auto-registered `agents:agentRun` mutation an HTTP-only client (e.g.
    * the `@lunora/mcp` server) calls. Default `false`: an agent is startable
-   * only from server-side app code (`ctx.agents.&lt;name>.run(...)`), so declaring
+   * only from server-side app code (`ctx.agents.<name>.run(...)`), so declaring
    * an agent does NOT expose it to arbitrary RPC callers. Fail-closed — the run
    * mutation refuses an agent that has not opted in, regardless of any MCP-side
    * `allowAgents` configuration. A started thread is still owner-scoped to
@@ -705,7 +711,7 @@ interface AgentAsToolOptions {
   /** Cap on child-run status polls before giving up. Default 120. */
   maxPolls?: number;
   /**
-   * The child agent's export name — selects its `AGENT_&lt;NAME>` Workflow
+   * The child agent's export name — selects its `AGENT_<NAME>` Workflow
    * binding (e.g. `"researcher"` → `AGENT_RESEARCHER`). The model-facing tool
    * name is the KEY assigned in the parent's `tools` map, not this.
    */
@@ -1095,7 +1101,7 @@ interface AgentRunHandle {
   id: string;
 }
 /**
- * The `ctx.agents.&lt;name>` producer handle.
+ * The `ctx.agents.<name>` producer handle.
  * @experimental
  */
 interface AgentHandle {
@@ -1128,4 +1134,4 @@ interface AgentHandle {
   /** Read a run's workflow status by instance id. */
   status: (id: string) => Promise<unknown>;
 }
-export { AgentDefinition as A, AgentEmailRun as B, AgentGenerateOptions as C, AgentGenerateResult as D, AgentInstructionsContext as E, AgentLiveEvent as F, AgentMemoryOptions as G, AgentMemorySource as H, InboundChannelEvent as I, AgentMessageStatus as J, AgentOnStepFinish as K, AgentPrepareStep as L, AgentPrepareStepInput as M, AgentPrepareStepResult as N, AgentProgressEvent as O, AgentRunHandle as P, AgentStepFinishInfo as Q, AgentStepInfo as R, SkillDefinition as S, AgentThreadStatus as T, AgentTokenDelta as U, AgentToolCall as V, AgentUsage as W, AgentVoiceConfig as X, AgentWorkflowBindingLike as Y, AgentWorkflowInstanceLike as Z, AgentToolContext as a, AgentToolDefinition as b, AgentCompact as c, AgentEpisodeExtract as d, AgentGraphExtract as e, AgentGenerate as f, AgentTokenSink as g, AgentRunInput as h, AgentFunctionPaths as i, AgentRunFunction as j, AgentStepLike as k, AgentStreamGenerate as l, AgentRunResult as m, AgentMessageRow as n, AgentConfig as o, AnyAgentTool as p, AgentAsToolOptions as q, AgentSubToolInput as r, AgentBindingSpec as s, AgentHandle as t, AgentToolConfig as u, AgentFunctionReference as v, AgentModelInput as w, SkillConfig as x, AgentApprovalContext as y, AgentEmailMapper as z };
+export { AgentDefinition as A, AgentEmailMapper as B, AgentEmailRun as C, AgentGenerateOptions as D, AgentGenerateResult as E, AgentInstructionsContext as F, AgentLiveEvent as G, AgentMemoryOptions as H, InboundChannelEvent as I, AgentMemorySource as J, AgentMessageStatus as K, AgentOnStepFinish as L, AgentPrepareStep as M, AgentPrepareStepInput as N, AgentPrepareStepResult as O, AgentProgressEvent as P, AgentRunHandle as Q, AgentStepFinishInfo as R, SkillMarkdownExtras as S, AgentStepInfo as T, AgentThreadStatus as U, AgentTokenDelta as V, AgentToolCall as W, AgentUsage as X, AgentVoiceConfig as Y, AgentWorkflowBindingLike as Z, AgentWorkflowInstanceLike as _, AgentToolContext as a, AgentToolDefinition as b, SkillDefinition as c, AgentCompact as d, AgentEpisodeExtract as e, AgentGraphExtract as f, AgentGenerate as g, AgentTokenSink as h, AgentRunInput as i, AgentFunctionPaths as j, AgentRunFunction as k, AgentStepLike as l, AgentStreamGenerate as m, AgentRunResult as n, AgentMessageRow as o, AgentConfig as p, AnyAgentTool as q, AgentAsToolOptions as r, AgentSubToolInput as s, AgentBindingSpec as t, AgentHandle as u, AgentToolConfig as v, AgentFunctionReference as w, AgentModelInput as x, SkillConfig as y, AgentApprovalContext as z };

package/dist/packem_shared/{types.d-BC_N2z6_.d.ts → types.d-PMYeuDE7.d.ts}

@@ -23,7 +23,7 @@ interface AgentStepLike {
   /**
    * Durably hibernate until an external event of `type` arrives, then return
    * its payload. Used for human-in-the-loop approvals: a run pauses on
-   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
+   * `approval:<toolCallId>` until a client resolves it. Like `do`, a resolved
    * wait is memoized — a replay returns the recorded decision without pausing
    * again. Signature mirrors `@lunora/workflow`'s `WorkflowStepLike`.
    */
@@ -42,7 +42,7 @@ interface AgentStepLike {
  * `idempotencyKey`.
  *
  * The `idempotencyKey` is the deterministic durable-step name
- * (`tool:&lt;name>:&lt;toolCallId>`). A COMPLETED tool step is never re-run on a
+ * (`tool:<name>:<toolCallId>`). A COMPLETED tool step is never re-run on a
  * workflow replay (native step memoization) — but a step that FAILS mid-body
  * is retried at-least-once, so a side-effecting tool (charge a card, send a
  * mail) must dedupe on this key itself.
@@ -138,7 +138,7 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    * Gate the tool behind a human approval (mirrors the AI SDK's
    * `needsApproval`). When it resolves truthy the durable run PAUSES — the
    * thread moves to `"awaiting_input"` and the workflow hibernates on
-   * `approval:&lt;toolCallId>` — until a client calls `agents:agentResolveApproval`.
+   * `approval:<toolCallId>` — until a client calls `agents:agentResolveApproval`.
    * On approve the tool runs exactly as normal; on reject it is skipped and a
    * tool result explaining the rejection is persisted so the next turn recovers.
    * A boolean gates statically; a function gates per input. Default: `false`
@@ -146,7 +146,7 @@ interface AgentToolDefinition<Input = unknown, Output = unknown> {
    *
    * The boolean/`undefined` forms are compile-time constants re-derived
    * identically on every replay — no durable step. The FUNCTION form runs
-   * inside its OWN durable step (`tool:approval-gate:&lt;toolCallId>`, distinct
+   * inside its OWN durable step (`tool:approval-gate:<toolCallId>`, distinct
    * from the tool's own step), so it now runs exactly once per call, not once
    * per replay. It must still be otherwise pure: deterministic given its
    * inputs (no `Date.now()`/`Math.random()`) and free of side effects — the
@@ -269,7 +269,7 @@ interface AgentMemoryOptions {
  * (`key: "default"`) from {@link AgentConfig.memory}, then one per skill that
  * carries `knowledge` (keyed by the skill's name). The key names the durable
  * step — the default source keeps the historic `"memory:retrieve"`, a skill
- * source uses `"memory:retrieve:&lt;key>"` — so replay stays deterministic.
+ * source uses `"memory:retrieve:<key>"` — so replay stays deterministic.
  * @experimental
  */
 interface AgentMemorySource extends AgentMemoryOptions {
@@ -325,7 +325,7 @@ interface SkillConfig {
   knowledge?: AgentMemoryOptions;
   /**
    * The skill's identifier — namespaces this skill's `knowledge` memory source
-   * (the durable step `memory:retrieve:&lt;name>`). Must be identifier-shaped.
+   * (the durable step `memory:retrieve:<name>`). Must be identifier-shaped.
    */
   name: string;
   /**
@@ -335,6 +335,12 @@ interface SkillConfig {
    */
   tools?: Record<string, AnyAgentTool>;
 }
+/**
+ * The code-side parts of a markdown-authored skill — everything `SKILL.md`
+ * cannot carry. `name` and `instructions` come from the file itself.
+ * @experimental
+ */
+type SkillMarkdownExtras = Omit<SkillConfig, "instructions" | "name">;
 /**
  * A `defineSkill` result — config plus the brand the agent merge checks.
  * @experimental
@@ -375,7 +381,7 @@ interface AgentStepFinishInfo {
 }
 /**
  * Called after each LLM turn with that turn's text, tool calls, and usage. Runs
- * inside a named durable step (`agent:step-finish:&lt;turn>`) so it fires exactly
+ * inside a named durable step (`agent:step-finish:<turn>`) so it fires exactly
  * once per turn even across a workflow replay.
  * @experimental
  */
@@ -547,7 +553,7 @@ interface AgentConfig {
   model: AgentModelInput;
   /**
    * Optional override for the deployed workflow name (`wrangler.jsonc`
-   * `workflows[].name`). Defaults to `agent-&lt;kebab-cased export name>`. Does
+   * `workflows[].name`). Defaults to `agent-<kebab-cased export name>`. Does
    * NOT change the binding name, which is always derived from the export
    * name (`support` → `AGENT_SUPPORT`).
    */
@@ -594,7 +600,7 @@ interface AgentConfig {
    * Opt this agent into being STARTED over the public RPC boundary — i.e. via
    * the auto-registered `agents:agentRun` mutation an HTTP-only client (e.g.
    * the `@lunora/mcp` server) calls. Default `false`: an agent is startable
-   * only from server-side app code (`ctx.agents.&lt;name>.run(...)`), so declaring
+   * only from server-side app code (`ctx.agents.<name>.run(...)`), so declaring
    * an agent does NOT expose it to arbitrary RPC callers. Fail-closed — the run
    * mutation refuses an agent that has not opted in, regardless of any MCP-side
    * `allowAgents` configuration. A started thread is still owner-scoped to
@@ -705,7 +711,7 @@ interface AgentAsToolOptions {
   /** Cap on child-run status polls before giving up. Default 120. */
   maxPolls?: number;
   /**
-   * The child agent's export name — selects its `AGENT_&lt;NAME>` Workflow
+   * The child agent's export name — selects its `AGENT_<NAME>` Workflow
    * binding (e.g. `"researcher"` → `AGENT_RESEARCHER`). The model-facing tool
    * name is the KEY assigned in the parent's `tools` map, not this.
    */
@@ -1095,7 +1101,7 @@ interface AgentRunHandle {
   id: string;
 }
 /**
- * The `ctx.agents.&lt;name>` producer handle.
+ * The `ctx.agents.<name>` producer handle.
  * @experimental
  */
 interface AgentHandle {
@@ -1128,4 +1134,4 @@ interface AgentHandle {
   /** Read a run's workflow status by instance id. */
   status: (id: string) => Promise<unknown>;
 }
-export { AgentDefinition as A, AgentEmailRun as B, AgentGenerateOptions as C, AgentGenerateResult as D, AgentInstructionsContext as E, AgentLiveEvent as F, AgentMemoryOptions as G, AgentMemorySource as H, InboundChannelEvent as I, AgentMessageStatus as J, AgentOnStepFinish as K, AgentPrepareStep as L, AgentPrepareStepInput as M, AgentPrepareStepResult as N, AgentProgressEvent as O, AgentRunHandle as P, AgentStepFinishInfo as Q, AgentStepInfo as R, SkillDefinition as S, AgentThreadStatus as T, AgentTokenDelta as U, AgentToolCall as V, AgentUsage as W, AgentVoiceConfig as X, AgentWorkflowBindingLike as Y, AgentWorkflowInstanceLike as Z, AgentToolContext as a, AgentToolDefinition as b, AgentCompact as c, AgentEpisodeExtract as d, AgentGraphExtract as e, AgentGenerate as f, AgentTokenSink as g, AgentRunInput as h, AgentFunctionPaths as i, AgentRunFunction as j, AgentStepLike as k, AgentStreamGenerate as l, AgentRunResult as m, AgentMessageRow as n, AgentConfig as o, AnyAgentTool as p, AgentAsToolOptions as q, AgentSubToolInput as r, AgentBindingSpec as s, AgentHandle as t, AgentToolConfig as u, AgentFunctionReference as v, AgentModelInput as w, SkillConfig as x, AgentApprovalContext as y, AgentEmailMapper as z };
+export { AgentDefinition as A, AgentEmailMapper as B, AgentEmailRun as C, AgentGenerateOptions as D, AgentGenerateResult as E, AgentInstructionsContext as F, AgentLiveEvent as G, AgentMemoryOptions as H, InboundChannelEvent as I, AgentMemorySource as J, AgentMessageStatus as K, AgentOnStepFinish as L, AgentPrepareStep as M, AgentPrepareStepInput as N, AgentPrepareStepResult as O, AgentProgressEvent as P, AgentRunHandle as Q, AgentStepFinishInfo as R, SkillMarkdownExtras as S, AgentStepInfo as T, AgentThreadStatus as U, AgentTokenDelta as V, AgentToolCall as W, AgentUsage as X, AgentVoiceConfig as Y, AgentWorkflowBindingLike as Z, AgentWorkflowInstanceLike as _, AgentToolContext as a, AgentToolDefinition as b, SkillDefinition as c, AgentCompact as d, AgentEpisodeExtract as e, AgentGraphExtract as f, AgentGenerate as g, AgentTokenSink as h, AgentRunInput as i, AgentFunctionPaths as j, AgentRunFunction as k, AgentStepLike as l, AgentStreamGenerate as m, AgentRunResult as n, AgentMessageRow as o, AgentConfig as p, AnyAgentTool as q, AgentAsToolOptions as r, AgentSubToolInput as s, AgentBindingSpec as t, AgentHandle as u, AgentToolConfig as v, AgentFunctionReference as w, AgentModelInput as x, SkillConfig as y, AgentApprovalContext as z };

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BC_N2z6_.mjs";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-PMYeuDE7.mjs";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
@@ -149,7 +149,7 @@ interface ContainerToolOptions {
 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`
+ * 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`.

package/dist/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-BC_N2z6_.js";
+import { a as AgentToolContext, b as AgentToolDefinition } from "./packem_shared/types.d-PMYeuDE7.js";
 import '@lunora/mail/inbound';
 import 'ai';
 /**
@@ -149,7 +149,7 @@ interface ContainerToolOptions {
 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`
+ * 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`.

package/dist/skill-markdown.d.mts

@@ -0,0 +1,36 @@
+import { S as SkillMarkdownExtras, c as SkillDefinition } from "./packem_shared/types.d-PMYeuDE7.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, c as SkillDefinition } from "./packem_shared/types.d-PMYeuDE7.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-DfJxCwfZ.mjs";const m=/^\uFEFF?[ \t]*---[ \t]*\r?\n/u,d=/^---[ \t]*$/mu,h=n=>{const r=m.exec(n);if(!r)return{body:n.trim(),data:{}};const t=n.slice(r[0].length),e=d.exec(t);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(t.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:t.slice(e.index+e[0].length).trim(),data:typeof a=="object"&&a!==null?a:{}}},c=(n,r={})=>{if(typeof n!="string")throw new o("INTERNAL",`@lunora/agent: skillFromMarkdown expects the markdown SOURCE as a string, got ${typeof n}`);const{body:t,data:e}=h(n);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(t==="")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:t,name:e.name})};export{c as skillFromMarkdown};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/agent",
-  "version": "1.0.0-alpha.40",
+  "version": "1.0.0-alpha.42",
   "description": "Durable AI agents for Lunora: defineAgent compiles a replay-safe tool-loop onto Cloudflare Workflows, with DO SQLite threads and live message subscriptions",
   "keywords": [
     "agent",
@@ -62,6 +62,10 @@
       "types": "./dist/naming.d.ts",
       "import": "./dist/naming.mjs"
     },
+    "./skill-markdown": {
+      "types": "./dist/skill-markdown.d.ts",
+      "import": "./dist/skill-markdown.mjs"
+    },
     "./sandbox": {
       "types": "./dist/sandbox.d.ts",
       "import": "./dist/sandbox.mjs"
@@ -76,14 +80,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/ai": "1.0.0-alpha.47",
-    "@lunora/errors": "1.0.0-alpha.13",
-    "@lunora/mail": "1.0.0-alpha.40",
-    "@lunora/server": "1.0.0-alpha.61",
-    "@lunora/values": "1.0.0-alpha.18",
-    "@lunora/workflow": "1.0.0-alpha.20",
+    "@lunora/ai": "1.0.0-alpha.48",
+    "@lunora/errors": "1.0.0-alpha.14",
+    "@lunora/mail": "1.0.0-alpha.41",
+    "@lunora/server": "1.0.0-alpha.62",
+    "@lunora/values": "1.0.0-alpha.19",
+    "@lunora/workflow": "1.0.0-alpha.21",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "ai": "7.0.37"
+    "ai": "7.0.37",
+    "yaml": "^2.9.0"
   },
   "engines": {
     "node": "^22.15.0 || >=24.11.0"