experimental-ash 0.6.1 → 0.7.0

package/dist/src/public/channels/slack/slackChannel.d.ts

@@ -38,6 +38,13 @@ export interface SlackInteractionAction {
     readonly actionId: string;
     readonly value?: string;
     readonly blockId?: string;
+    /**
+     * `ts` of the Slack message that hosts the clicked component. Required by
+     * handlers that want to update the clicked message in place via
+     * `chat.update` — `ctx.slack.threadTs` resolves to the thread root for
+     * components clicked inside thread replies, not to the clicked message.
+     */
+    readonly messageTs?: string;
 }
 export type SlackRunResult = {
     auth: import("#channel/types.js").SessionAuthContext | null;

package/dist/src/public/channels/slack/slackChannel.js

@@ -67,11 +67,16 @@ function parseBlockActionsPayload(body) {
     const team = body.team;
     const user = body.user;
     const teamId = team?.id ?? user?.team_id;
+    // `message.ts` is the ts of the message that hosts the clicked component.
+    // It differs from `threadTs` whenever the bot's message is a thread reply,
+    // and is required for `chat.update` on the clicked message.
+    const messageTs = typeof message?.ts === "string" ? message.ts : undefined;
     return {
         actions: actions.map((a) => ({
             actionId: String(a.action_id ?? ""),
             value: a.value != null ? String(a.value) : undefined,
             blockId: a.block_id != null ? String(a.block_id) : undefined,
+            messageTs,
         })),
         channelId: channel,
         threadTs,

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/definitions/sandbox-backend.d.ts

@@ -1,126 +1,4 @@
-import type { SandboxBootstrapContext, SandboxSession, SandboxSessionUseFn } from "#public/definitions/sandbox.js";
-/**
- * Live sandbox handle returned by a {@link SandboxBackend}.
- *
- * Wraps the public {@link SandboxSession} with lifecycle methods so the
- * runtime orchestrator can persist reconnect metadata and release
- * resources.
- */
-export interface SandboxBackendHandle<S extends SandboxSession = SandboxSession> {
-    readonly session: SandboxSession;
-    readonly useSessionFn: SandboxSessionUseFn<S>;
-    captureState(): Promise<SandboxBackendSessionState>;
-    dispose(): Promise<void>;
-}
-/**
- * Serializable per-sandbox reconnect record stored on the harness session.
- *
- * `backendName` matches the {@link SandboxBackend.name} of the backend
- * that produced this state, and is used by the runtime to decide whether
- * a previously persisted handle is still compatible with the current
- * backend.
- */
-export interface SandboxBackendSessionState {
-    readonly backendName: string;
-    readonly metadata: Record<string, unknown>;
-    readonly sessionKey: string;
-}
-/**
- * One file written into a sandbox template before snapshot capture.
- */
-export interface SandboxSeedFile {
-    readonly path: string;
-    readonly content: string | Buffer;
-}
-/**
- * Diagnostic tags attached to provider-owned sandbox resources.
- *
- * Built-in backends may forward these into their hosting platform's
- * native tagging system. Ash supplies stable tags such as the active
- * agent, channel, and session id so sandboxes can be found and
- * attributed in provider dashboards.
- */
-export type SandboxBackendTags = Readonly<Record<string, string>>;
-/**
- * Framework-owned runtime context handed to a backend on every
- * {@link SandboxBackend.create} call.
- *
- * Backends use this to derive any per-call state that depends on the
- * surrounding application — for example, the local backend computes its
- * cache directory from `appRoot`. Backends that don't need anything
- * here may ignore the field entirely.
- */
-export interface SandboxBackendRuntimeContext {
-    readonly appRoot: string;
-}
-/**
- * Input passed to {@link SandboxBackend.create} when the runtime needs a
- * live sandbox session.
- */
-export interface SandboxBackendCreateInput {
-    readonly templateKey: string;
-    readonly sessionKey: string;
-    readonly existingMetadata?: Record<string, unknown>;
-    /**
-     * Runtime tags the backend should attach to sandbox resources when
-     * the underlying provider supports tags.
-     */
-    readonly tags?: SandboxBackendTags;
-    readonly runtimeContext: SandboxBackendRuntimeContext;
-}
-/**
- * Input passed to {@link SandboxBackend.prewarm} when the build pipeline
- * is preparing reusable templates.
- *
- * Every authored sandbox in the compiled graph receives exactly one
- * `prewarm(...)` call before runtime opens its first session. The
- * backend captures a reusable template snapshot from the supplied
- * `bootstrap` hook and `seedFiles`, then `backend.create(...)` opens
- * durable sessions from that snapshot.
- */
-export interface SandboxBackendPrewarmInput {
-    readonly templateKey: string;
-    readonly bootstrap?: (input: SandboxBootstrapContext) => void | Promise<void>;
-    readonly runtimeContext: SandboxBackendRuntimeContext;
-    readonly seedFiles: ReadonlyArray<SandboxSeedFile>;
-}
-/**
- * Pluggable sandbox backend.
- *
- * A `SandboxBackend` is a value an author attaches to a
- * {@link SandboxDefinition} to choose which underlying runtime hosts the
- * sandbox. Ash ships two built-in backends — `vercelBackend()` and
- * `localBackend()` — but the interface is public so authors can write
- * their own.
- *
- * Each backend owns the full template-then-session lifecycle internally;
- * callers only need a single `create` call.
- */
-export interface SandboxBackend<S extends SandboxSession = SandboxSession> {
-    /**
-     * Stable identifier for this backend implementation.
-     *
-     * Participates in cache-key derivation and the persisted reconnect
-     * state, so two backends that should not share template snapshots
-     * must use distinct names. Built-in backends use `"vercel"` and
-     * `"local"`. Custom backends pick a unique string.
-     */
-    readonly name: string;
-    /**
-     * Creates or reattaches one live sandbox session from a template
-     * previously captured by {@link SandboxBackend.prewarm}. Throws
-     * {@link SandboxTemplateNotProvisionedError} when the requested
-     * template is missing.
-     */
-    create(input: SandboxBackendCreateInput): Promise<SandboxBackendHandle<S>>;
-    /**
-     * Build-time prewarm hook. Ash invokes this for every authored
-     * sandbox in the compiled graph before serving traffic so the backend
-     * can capture a reusable template snapshot. Idempotent against an
-     * existing snapshot keyed by `templateKey`.
-     */
-    prewarm(input: SandboxBackendPrewarmInput): Promise<void>;
-}
+export type { SandboxBackendHandle, SandboxBackendSessionState, SandboxSeedFile, SandboxBackendTags, SandboxBackendRuntimeContext, SandboxBackendCreateInput, SandboxBackendPrewarmInput, SandboxBackend, } from "#shared/sandbox-backend.js";
 export declare class SandboxTemplateNotProvisionedError extends Error {
     readonly backendName: string;
     readonly templateKey: string;

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

@@ -1,168 +1,9 @@
-import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
-/**
- * Serializable result returned after running one sandbox command.
- */
-export interface SandboxCommandResult {
-    readonly exitCode: number;
-    readonly stderr: string;
-    readonly stdout: string;
-}
-/**
- * Options for reading a text file from a sandbox with optional line ranges.
- */
-export interface SandboxReadFileOptions {
-    /**
-     * 1-based inclusive end line. When past the file's line count, the read
-     * returns through EOF without error.
-     */
-    readonly endLine?: number;
-    /**
-     * 1-based inclusive start line. Defaults to 1.
-     */
-    readonly startLine?: number;
-}
-/**
- * Minimal Ash-owned sandbox session exposed to authored lifecycle hooks.
- */
-export interface SandboxSession {
-    /**
-     * Stable identifier for the backend session this handle wraps.
-     *
-     * Persists across reconnects to the same logical session: two calls
-     * that resume the same underlying backend sandbox observe the same
-     * `id`. Template sessions constructed during bootstrap expose the
-     * template key; live sessions expose the session key assigned by the
-     * runtime. Useful as a cache key for per-session state that must
-     * outlive individual step executions.
-     */
-    readonly id: string;
-    /**
-     * Reads one text file from the sandbox as UTF-8.
-     *
-     * Returns `null` when the file does not exist. Throws when the file
-     * contains invalid UTF-8.
-     *
-     * Relative paths resolve from `/workspace`, the live working directory
-     * for every backend. Absolute paths pass through unchanged.
-     *
-     * Line ranges are 1-based and inclusive. When `endLine` is past EOF the
-     * read returns through EOF without error.
-     */
-    readFile(path: string, options?: SandboxReadFileOptions): Promise<string | null>;
-    /**
-     * Reads one file from the sandbox as raw bytes.
-     *
-     * Returns `null` when the file does not exist. Unlike
-     * {@link SandboxSession.readFile}, this variant performs no UTF-8
-     * decoding and is safe for binary payloads (images, PDFs, archives,
-     * attachment bytes written by the framework at
-     * `/workspace/attachments/...`).
-     *
-     * Relative paths resolve from `/workspace`, the live working
-     * directory for every backend. Absolute paths pass through unchanged.
-     */
-    readFileBytes(path: string): Promise<Buffer | null>;
-    /**
-     * Anchors a sandbox-relative path to `/workspace` and returns the
-     * resulting absolute path.
-     *
-     * Relative paths resolve from `/workspace`; absolute paths pass through.
-     * `readFile(...)` and `writeFile(...)` already apply this internally.
-     */
-    resolvePath(path: string): string;
-    /**
-     * Runs one shell command inside the current sandbox session and returns the
-     * captured stdout, stderr, and exit code.
-     *
-     * Commands execute with `/workspace` as the working directory on every
-     * backend.
-     */
-    runCommand(command: string): Promise<SandboxCommandResult>;
-    /**
-     * Writes one file to the sandbox, creating parent directories
-     * recursively and overwriting any existing file.
-     *
-     * `content` accepts a UTF-8 `string` for text files or a `Buffer` for
-     * arbitrary bytes. The framework uses the `Buffer` overload to mount
-     * binary workspace assets (images under skill `assets/` directories,
-     * fixture payloads, and so on) through the same public surface authors
-     * use.
-     *
-     * Relative paths resolve from `/workspace`. Absolute paths pass through
-     * unchanged.
-     */
-    writeFile(path: string, content: string | Buffer): Promise<void>;
-}
-/**
- * A transform applied to network requests matching a domain rule.
- */
-export interface SandboxNetworkTransformer {
-    readonly headers?: Record<string, string>;
-}
-/**
- * A rule applied to requests matching a domain in the network policy.
- */
-export interface SandboxNetworkPolicyRule {
-    readonly transform?: SandboxNetworkTransformer[];
-}
-/**
- * Network policy to define network restrictions for the sandbox.
- *
- * - `"allow-all"`: Full internet access (default). All traffic is allowed.
- * - `"deny-all"`: No internet access. All traffic is denied.
- * - Object: Custom access with explicit allow/deny lists.
- */
-export type SandboxNetworkPolicy = "allow-all" | "deny-all" | {
-    readonly allow?: string[] | Readonly<Record<string, SandboxNetworkPolicyRule[]>>;
-};
-export interface SandboxBootstrapUseOptions {
-    readonly runtime?: string;
-    readonly ports?: number[];
-    readonly env?: Record<string, string>;
-}
-export interface SandboxSessionUseOptions {
-    readonly networkPolicy?: SandboxNetworkPolicy;
-    readonly resources?: {
-        vcpus?: number;
-    };
-    readonly timeout?: number;
-    readonly tags?: Record<string, string>;
-}
-export type SandboxBootstrapUseFn = (options?: SandboxBootstrapUseOptions) => Promise<SandboxSession>;
-export type SandboxSessionUseFn<S extends SandboxSession = SandboxSession> = (options?: SandboxSessionUseOptions) => Promise<S>;
-export interface SandboxBootstrapContext {
-    readonly use: SandboxBootstrapUseFn;
-}
-export interface SandboxSessionContext<S extends SandboxSession = SandboxSession> {
-    readonly use: SandboxSessionUseFn<S>;
-}
-/**
- * Public sandbox definition authored in `agent/sandbox.ts` (shorthand)
- * or `agent/sandbox/sandbox.ts` (folder layout, when paired with an
- * authored `sandbox/workspace/` subtree).
- *
- * Each agent (and each subagent) owns exactly one sandbox. When the
- * module file is absent the framework auto-provides a default sandbox
- * via `defaultBackend()`. Authors override lifecycle and backend by
- * creating `agent/sandbox.ts` (or `agent/sandbox/sandbox.ts` when they
- * also want a workspace folder); subagents override independently via
- * `subagents/<name>/sandbox.ts` (or the folder form) and do not inherit
- * their parent's sandbox (skill seeds differ per agent).
- */
-export interface SandboxDefinition<S extends SandboxSession = SandboxSession> {
-    /**
-     * Backend that runs this sandbox.
-     *
-     * When this field is omitted, Ash substitutes `defaultBackend()` at
-     * runtime, which delegates to `vercelBackend()` on hosted Vercel
-     * (where `process.env.VERCEL` is set) and to `localBackend()`
-     * everywhere else. Set `backend` explicitly to pin the sandbox to a
-     * specific backend regardless of environment.
-     */
-    readonly backend?: SandboxBackend<S>;
-    bootstrap?(input: SandboxBootstrapContext): Promise<void> | void;
-    onSession?(input: SandboxSessionContext<S>): Promise<void> | void;
-}
+import type { Optional } from "#shared/optional.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { SandboxDefinition as SharedSandboxDefinition } from "#shared/sandbox-definition.js";
+export type { SandboxCommandOptions, SandboxCommandResult, SandboxReadFileOptions, SandboxSession, } from "#shared/sandbox-session.js";
+export type { SandboxNetworkPolicy, SandboxBootstrapUseOptions, SandboxSessionUseOptions, SandboxBootstrapUseFn, SandboxSessionUseFn, SandboxBootstrapContext, SandboxSessionContext, } from "#shared/sandbox-definition.js";
+export type SandboxDefinition<S extends SandboxSession = SandboxSession> = Optional<SharedSandboxDefinition<S>, "backend">;
 /**
  * Defines a sandbox configuration.
  */

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/public/sandbox/index.d.ts

@@ -3,7 +3,7 @@
  * `agent/sandbox/sandbox.ts` when paired with a `workspace/` folder).
  */
 export { getSandbox } from "#context/accessors.js";
-export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxBootstrapUseOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxNetworkPolicy, type SandboxReadFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxSessionUseOptions, } from "#public/definitions/sandbox.js";
+export { defineSandbox, type SandboxBootstrapContext, type SandboxBootstrapUseFn, type SandboxBootstrapUseOptions, type SandboxCommandOptions, type SandboxCommandResult, type SandboxDefinition, type SandboxNetworkPolicy, type SandboxReadFileOptions, type SandboxSession, type SandboxSessionContext, type SandboxSessionUseFn, type SandboxSessionUseOptions, } from "#public/definitions/sandbox.js";
 export type { SandboxBackend, SandboxBackendCreateInput, SandboxBackendHandle, SandboxBackendPrewarmInput, SandboxBackendRuntimeContext, SandboxBackendSessionState, SandboxSeedFile, } from "#public/definitions/sandbox-backend.js";
 export { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
 export { defaultBackend } from "#public/sandbox/backends/default.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

@@ -3,8 +3,6 @@ import type { ChannelAdapter } from "#channel/adapter.js";
 import type { DiscoverDiagnosticsSummary } from "#discover/diagnostics.js";
 import type { ChannelMethod, Route, RouteContext } from "#public/definitions/channel.js";
 import type { RouteHandler } from "#channel/routes.js";
-import type { SandboxBootstrapContext, SandboxSessionContext } from "#public/definitions/sandbox.js";
-import type { SandboxBackend } from "#public/definitions/sandbox-backend.js";
 import type { LifecycleHooks, StreamEventHook } from "#public/definitions/hook.js";
 import type { CompactionHookInput, CompactionHookResult, NeedsApprovalContext, ToolRetentionPolicy } from "#public/definitions/tool.js";
 import type { AuthorizationDefinition, HeadersDefinition, ToolFilterDefinition } from "#runtime/connections/types.js";
@@ -16,17 +14,21 @@ import type { SourceRef, ModuleSourceRef, SkillPackageSourceRef, MarkdownSourceR
 import type { InternalSkillDefinition } from "#shared/skill-definition.js";
 import type { InternalAgentDefinition } from "#shared/agent-definition.js";
 import type { InternalToolDefinitionWithExecuteFn } from "#shared/tool-definition.js";
+import type { SandboxDefinition } from "#shared/sandbox-definition.js";
+import type { SandboxSession } from "#shared/sandbox-session.js";
 /**
  * Runtime-owned source ref describing one additive config module import.
  */
 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)>;
@@ -77,18 +79,15 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
  * map.
  *
  * The resolved `backend` is non-optional: every sandbox in the runtime
- * graph carries a concrete {@link SandboxBackend} value, even when the
+ * graph carries a concrete SandboxBackend value, even when the
  * authored definition omits `backend`. The unauthored case is filled
  * in by `defaultBackend()` (which itself selects between
  * `vercelBackend()` and `localBackend()` based on the current
  * environment).
  */
-export interface ResolvedSandboxDefinition extends ResolvedModuleSourceRef {
-    readonly backend: SandboxBackend;
-    readonly bootstrap?: (input: SandboxBootstrapContext) => Promise<void> | void;
+export type ResolvedSandboxDefinition = Readonly<SandboxDefinition<SandboxSession>> & ResolvedModuleSourceRef & {
     readonly description?: string;
-    readonly onSession?: (input: SandboxSessionContext) => Promise<void> | void;
-}
+};
 /**
  * Runtime-owned authored tool definition resolved from a compiled module map.
  * A tool without `execute` is surfaced to the client and never executed by Ash.
@@ -235,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.