experimental-ash 0.6.2 → 0.7.0

package/dist/src/public/definitions/instructions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public definition for an instructions prompt authored in markdown or
+ * TypeScript.
+ *
+ * Authored at the agent root as either `instructions.md` or
+ * `instructions.{ts,cts,mts,js,cjs,mjs}`. Module-backed instructions
+ * sources execute once at build time — the resulting markdown is captured
+ * into the compiled manifest. Authored definitions do not carry a `name`
+ * field.
+ */
+export interface InstructionsDefinition {
+    markdown: string;
+}
+/**
+ * Defines an instructions prompt in TypeScript using the same shape
+ * discovery produces from markdown.
+ */
+export declare function defineInstructions<TInstructions extends InstructionsDefinition>(definition: TInstructions): TInstructions;
+/**
+ * @deprecated Use {@link InstructionsDefinition} instead. The authored
+ * file slot was renamed from `system.{md,ts,...}` to
+ * `instructions.{md,ts,...}`.
+ */
+export type SystemDefinition = InstructionsDefinition;
+/**
+ * @deprecated Use {@link defineInstructions} instead. The authored file
+ * slot was renamed from `system.{md,ts,...}` to `instructions.{md,ts,...}`.
+ */
+export declare const defineSystem: typeof defineInstructions;

package/dist/src/public/definitions/instructions.js

@@ -0,0 +1,12 @@
+/**
+ * Defines an instructions prompt in TypeScript using the same shape
+ * discovery produces from markdown.
+ */
+export function defineInstructions(definition) {
+    return definition;
+}
+/**
+ * @deprecated Use {@link defineInstructions} instead. The authored file
+ * slot was renamed from `system.{md,ts,...}` to `instructions.{md,ts,...}`.
+ */
+export const defineSystem = defineInstructions;

package/dist/src/public/helpers/markdown.d.ts

@@ -1,6 +1,6 @@
 import { type ScheduleDefinition } from "#public/definitions/schedule.js";
 import { type SkillDefinition } from "#public/definitions/skill.js";
-import { type SystemDefinition } from "#public/definitions/system.js";
+import { type InstructionsDefinition } from "#public/definitions/instructions.js";
 /**
  * Parsed markdown document with optional YAML frontmatter.
  */
@@ -24,11 +24,11 @@ export interface ParsedMarkdownDocument {
  */
 export declare function parseMarkdownDocument(source: string): ParsedMarkdownDocument;
 /**
- * Lowers authored system prompt markdown into the shared public definition
- * shape. System identity is path-derived, so the lowered definition never
- * carries a `name`.
+ * Lowers authored instructions prompt markdown into the shared public
+ * definition shape. Instructions identity is path-derived, so the lowered
+ * definition never carries a `name`.
  */
-export declare function lowerSystemMarkdown(markdown: string): SystemDefinition;
+export declare function lowerInstructionsMarkdown(markdown: string): InstructionsDefinition;
 /**
  * Optional input for {@link lowerSkillMarkdown}.
  *

package/dist/src/public/helpers/markdown.js

@@ -1,9 +1,9 @@
 import grayMatter from "gray-matter";
-import { normalizeScheduleDefinition, normalizeSkillDefinition, normalizeSystemDefinition, } from "#internal/authored-definition/core.js";
+import { normalizeScheduleDefinition, normalizeSkillDefinition, normalizeInstructionsDefinition, } from "#internal/authored-definition/core.js";
 import { isObject } from "#shared/guards.js";
 import { defineSchedule } from "#public/definitions/schedule.js";
 import { defineSkill } from "#public/definitions/skill.js";
-import { defineSystem } from "#public/definitions/system.js";
+import { defineInstructions, } from "#public/definitions/instructions.js";
 const CLOSED_FRONTMATTER_PATTERN = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;
 /**
  * Parses markdown with optional YAML frontmatter.
@@ -36,12 +36,12 @@ export function parseMarkdownDocument(source) {
     };
 }
 /**
- * Lowers authored system prompt markdown into the shared public definition
- * shape. System identity is path-derived, so the lowered definition never
- * carries a `name`.
+ * Lowers authored instructions prompt markdown into the shared public
+ * definition shape. Instructions identity is path-derived, so the lowered
+ * definition never carries a `name`.
  */
-export function lowerSystemMarkdown(markdown) {
-    return defineSystem(normalizeSystemDefinition({ markdown }, "Expected authored system markdown to match the public Ash shape."));
+export function lowerInstructionsMarkdown(markdown) {
+    return defineInstructions(normalizeInstructionsDefinition({ markdown }, "Expected authored instructions markdown to match the public Ash shape."));
 }
 /**
  * Lowers authored skill markdown into the shared public definition shape.

package/dist/src/public/instructions/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Instructions prompt authoring helpers for `agent/instructions.ts` files.
+ */
+export { defineInstructions, type InstructionsDefinition, 
+/** @deprecated Use {@link defineInstructions} instead. */
+defineSystem, 
+/** @deprecated Use {@link InstructionsDefinition} instead. */
+type SystemDefinition, } from "#public/definitions/instructions.js";

package/dist/src/public/instructions/index.js

@@ -0,0 +1,6 @@
+/**
+ * Instructions prompt authoring helpers for `agent/instructions.ts` files.
+ */
+export { defineInstructions, 
+/** @deprecated Use {@link defineInstructions} instead. */
+defineSystem, } from "#public/definitions/instructions.js";

package/dist/src/runtime/agent/bootstrap.js

@@ -19,7 +19,7 @@ export function createResolvedRuntimeTurnAgent(input) {
         id: agent.config.name,
         instructions: composeRuntimeBasePrompt({
             connections: agent.connections,
-            system: agent.system,
+            instructions: agent.instructions,
             skills: agent.skills,
             toolsAvailable: input.tools.length > 0,
             workspaceSpec: agent.workspaceSpec,
@@ -39,8 +39,8 @@ function createResolvedTurnMetadata(agent) {
             ...agent.config.metadata,
         };
     }
-    if (agent.system !== undefined) {
-        metadata.systemName = agent.system.name;
+    if (agent.instructions !== undefined) {
+        metadata.instructionsName = agent.instructions.name;
     }
     if (agent.skills.length > 0) {
         metadata.skillNames = agent.skills.map((skill) => skill.name);

package/dist/src/runtime/prompt/compose.d.ts

@@ -1,17 +1,18 @@
-import type { ResolvedConnectionDefinition, ResolvedSkillDefinition, ResolvedSystem } from "#runtime/types.js";
+import type { ResolvedConnectionDefinition, ResolvedInstructions, ResolvedSkillDefinition } from "#runtime/types.js";
 import type { WorkspaceRuntimeSpec } from "#runtime/workspace/types.js";
 /**
- * Input for composing the base authored system prompt for one resolved agent.
+ * Input for composing the base authored instructions prompt for one
+ * resolved agent.
  */
 export interface ComposeRuntimeBasePromptInput {
     connections?: readonly ResolvedConnectionDefinition[];
-    system?: ResolvedSystem;
+    instructions?: ResolvedInstructions;
     skills?: readonly ResolvedSkillDefinition[];
     toolsAvailable?: boolean;
     workspaceSpec?: WorkspaceRuntimeSpec;
 }
 /**
- * Composes the authored base prompt from the resolved system source
+ * Composes the authored base prompt from the resolved instructions source
  * without flattening skills into always-on instructions.
  */
 export declare function composeRuntimeBasePrompt(input: ComposeRuntimeBasePromptInput): readonly string[];

package/dist/src/runtime/prompt/compose.js

@@ -3,27 +3,27 @@ import { createWorkspacePromptSection } from "#runtime/workspace/spec.js";
 import { formatConnectionsSection } from "#runtime/prompt/connections.js";
 const PARALLEL_ACTION_INSTRUCTION = "Tool execution\nA single tool or subagent call runs as one serial action. If you call multiple independent tools or subagents in one response, Ash treats that batch as parallel work. Only batch work that is independent and does not rely on another call in the same response.";
 /**
- * Composes the authored base prompt from the resolved system source
+ * Composes the authored base prompt from the resolved instructions source
  * without flattening skills into always-on instructions.
  */
 export function composeRuntimeBasePrompt(input) {
     return [
-        ...createSystemPromptBlocks(input.system),
+        ...createInstructionsPromptBlocks(input.instructions),
         ...createWorkspacePromptBlocks(input.workspaceSpec),
         ...(input.toolsAvailable ? [PARALLEL_ACTION_INSTRUCTION] : []),
         ...createConnectionsPromptBlocks(input.connections),
         ...createSkillsPromptBlocks(input.skills),
     ];
 }
-function createSystemPromptBlocks(system) {
-    if (system === undefined) {
+function createInstructionsPromptBlocks(instructions) {
+    if (instructions === undefined) {
         return [];
     }
-    const markdown = system.markdown.trim();
+    const markdown = instructions.markdown.trim();
     if (markdown.length === 0) {
         return [];
     }
-    return [`System (${system.name})\n${markdown}`];
+    return [`Instructions (${instructions.name})\n${markdown}`];
 }
 function createWorkspacePromptBlocks(workspaceSpec) {
     if (workspaceSpec === undefined) {

package/dist/src/runtime/resolve-agent.js

@@ -41,7 +41,7 @@ export async function resolveAgent(input) {
     const authoredSandbox = input.manifest.sandbox === null
         ? null
         : await resolveSandboxDefinition(input.manifest.sandbox, input.moduleMap, input.nodeId);
-    const system = createResolvedSystem(input.manifest.system);
+    const instructions = createResolvedInstructions(input.manifest.instructions);
     const workspaceResourceRoot = input.manifest.workspaceResourceRoot;
     const resolvedAgent = {
         channels: resolvedChannels,
@@ -61,21 +61,21 @@ export async function resolveAgent(input) {
         tools: resolvedTools,
         workspaceSpec: { rootEntries: [...workspaceResourceRoot.rootEntries] },
     };
-    if (system !== undefined) {
-        return { ...resolvedAgent, system };
+    if (instructions !== undefined) {
+        return { ...resolvedAgent, instructions };
     }
     return resolvedAgent;
 }
-function createResolvedSystem(system) {
-    if (system === undefined) {
+function createResolvedInstructions(instructions) {
+    if (instructions === undefined) {
         return undefined;
     }
     return {
-        name: system.name,
-        logicalPath: system.logicalPath,
-        markdown: system.markdown,
-        sourceId: system.sourceId,
-        sourceKind: system.sourceKind,
+        name: instructions.name,
+        logicalPath: instructions.logicalPath,
+        markdown: instructions.markdown,
+        sourceId: instructions.sourceId,
+        sourceKind: instructions.sourceKind,
     };
 }
 function createResolvedAgentConfig(manifest) {

package/dist/src/runtime/types.d.ts

@@ -21,12 +21,14 @@ import type { SandboxSession } from "#shared/sandbox-session.js";
  */
 export type ResolvedModuleSourceRef = Readonly<ModuleSourceRef>;
 /**
- * Authored system prompt resolved from `system.md` or `system.{ts,...}`.
+ * Authored instructions prompt resolved from `instructions.md` or
+ * `instructions.{ts,...}`.
  *
- * Module-backed system sources are executed once at build time — the resulting
- * markdown is captured here. Runtime never re-evaluates the module.
+ * Module-backed instructions sources are executed once at build time —
+ * the resulting markdown is captured here. Runtime never re-evaluates
+ * the module.
  */
-export type ResolvedSystem = Readonly<SourceRef & {
+export type ResolvedInstructions = Readonly<SourceRef & {
     name: string;
     markdown: string;
 } & (Omit<MarkdownSourceRef<undefined>, "definition"> | ModuleSourceRef)>;
@@ -232,10 +234,11 @@ export interface ResolvedAgent {
     readonly disabledFrameworkTools: readonly string[];
     readonly metadata: ResolvedAgentMetadata;
     /**
-     * Authored system prompt resolved from `system.md` or `system.{ts,...}`,
-     * or `undefined` when the agent does not declare one.
+     * Authored instructions prompt resolved from `instructions.md` or
+     * `instructions.{ts,...}`, or `undefined` when the agent does not
+     * declare one.
      */
-    readonly system?: ResolvedSystem;
+    readonly instructions?: ResolvedInstructions;
     /**
      * Authored sandbox override for this agent, when one exists. `null`
      * means the agent uses the framework default sandbox unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -90,10 +90,15 @@
       "import": "./dist/src/public/skills/index.js",
       "default": "./dist/src/public/skills/index.js"
     },
+    "./instructions": {
+      "types": "./dist/src/public/instructions/index.d.ts",
+      "import": "./dist/src/public/instructions/index.js",
+      "default": "./dist/src/public/instructions/index.js"
+    },
     "./system": {
-      "types": "./dist/src/public/system/index.d.ts",
-      "import": "./dist/src/public/system/index.js",
-      "default": "./dist/src/public/system/index.js"
+      "types": "./dist/src/public/instructions/index.d.ts",
+      "import": "./dist/src/public/instructions/index.js",
+      "default": "./dist/src/public/instructions/index.js"
     },
     "./context": {
       "types": "./dist/src/public/context/index.d.ts",