experimental-ash 0.2.0-alpha.2 → 0.2.0-alpha.21

package/docs/public/cli-build-and-debugging.md

@@ -67,7 +67,7 @@ When something is wrong:
 3. confirm the file is in the right authored slot
 4. confirm the root-vs-subagent boundary is valid
 5. confirm secrets are coming from env vars, not hard-coded values
-6. replay the run and inspect the stream events
+6. replay the session and inspect the stream events
 
 ## Common Gotchas
 

package/docs/public/context-control.md

@@ -36,8 +36,9 @@ Ash loads these layers deterministically by path, so keep filenames stable and i
 
 Skills are not part of the always-on prompt by default.
 
-Instead, Ash advertises available skills and adds a framework-owned `activate_skill` tool. When the
-model activates a skill, that skill's markdown is appended to the active system instructions for
+Instead, Ash advertises available skills and adds a framework-owned `load_skill` tool. When the
+request clearly matches a skill description, or the user names a skill explicitly, the model should
+activate that skill. Ash then appends the skill's markdown to the active system instructions for
 later turn work.
 
 This is how you keep rich procedures available without bloating every turn.
@@ -67,6 +68,10 @@ remaining uncertainty.
 Packaged skills are useful when you also want sibling files such as `references/`, `assets/`, or
 `scripts/` under the same skill directory.
 
+Those packaged paths also show up under the runtime workspace root, so the model can inspect them
+with the normal file or shell tools instead of requiring all of that content to be pasted into the
+prompt.
+
 ### Skill Rules That Matter
 
 - packaged `SKILL.md` files must include YAML frontmatter
@@ -132,4 +137,3 @@ For most agents:
 - [`skills.md`](./skills.md)
 - [`workspace.md`](./workspace.md)
 - [`subagents.md`](./subagents.md)
-

package/docs/public/evals.md

@@ -5,8 +5,8 @@ command.
 
 Use evals when you want to:
 
-- guard a prompt or tool change with real runs
-- compare output against expected text, JSON, SQL, or run behavior
+- guard a prompt or tool change with real sessions
+- compare output against expected text, JSON, SQL, or session behavior
 - export results to Braintrust for review and comparison
 
 ## Where Evals Live
@@ -76,7 +76,7 @@ Common optional suite fields:
 An eval case is a small input/expected pair plus optional tags and metadata.
 
 `input` may be either a string or an object. `expected` is optional, which is useful for behavior
-checks that only care about the run itself.
+checks that only care about the session itself.
 
 You can provide cases directly:
 

package/docs/public/getting-started.md

@@ -96,7 +96,7 @@ Useful commands:
 
 ## Send A Message
 
-Start a durable run:
+Start a durable session:
 
 ```bash
 curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
@@ -107,35 +107,38 @@ curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
 Ash responds quickly with:
 
 - a `continuationToken` in the JSON body
-- an `x-ash-run-id` header for the stream route
+- an `x-ash-session-id` header for the stream route
 
-## Stream The Run
+## Stream The Session
 
-Attach to the run stream:
+Attach to the session stream:
 
 ```bash
-curl http://127.0.0.1:3000/.well-known/ash/v1/runs/<runId>/stream
+curl http://127.0.0.1:3000/.well-known/ash/v1/sessions/<sessionId>/stream
 ```
 
 The stream is NDJSON. Expect lifecycle events such as:
 
-- `run.started`
+- `session.started`
 - `turn.started`
 - `message.received`
+- `step.started`
 - `actions.requested`
 - `action.result`
 - `subagent.started`
 - `subagent.event`
 - `subagent.completed`
-- `thinking.completed`
+- `reasoning.completed`
 - `message.completed`
+- `step.completed`
 - `turn.completed`
 - `session.waiting`
-- `run.completed`
+- `session.completed`
+- `session.failed`
 
-`message.completed.data.finishReason` tells you why the assistant step ended.
-`tool-calls` means the agent is continuing; other values are terminal for the
-current turn.
+`message.completed.data.finishReason` tells you whether assistant text is
+interim tool-call narration or a terminal reply. `step.completed.data.finishReason`
+still carries the same step outcome, and `step.completed.data.usage` carries usage.
 
 ## Send A Follow-Up Message
 
@@ -153,4 +156,4 @@ curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
 - [`agent-ts.md`](./agent-ts.md) for runtime config
 - [`skills.md`](./skills.md) for on-demand procedures
 - [`tools.md`](./tools.md) for typed integrations
-- [`runs-and-streaming.md`](./runs-and-streaming.md) for the durable runtime model
+- [`runs-and-streaming.md`](./runs-and-streaming.md) for the durable session model

package/docs/public/human-in-the-loop.md

@@ -5,17 +5,18 @@ Ash supports human-in-the-loop (HITL) in two forms:
 - tool approval requests
 - explicit user questions via the framework `ask_question` tool
 
-Both use the same runtime flow:
+Both use the same unified `InputRequest` / `InputResponse` protocol:
 
 1. the model requests input
 2. Ash emits an `input.requested` stream event
-3. the run parks at `session.waiting`
+3. the turn parks at `session.waiting`
 4. the client either:
-   - sends `inputResults`
+   - sends `inputResponses` (structured answers keyed by `requestId`)
    - or sends a normal follow-up `message` instead
 
-If the user sends a normal follow-up message instead of answering, Ash treats the pending HITL
-requests as ignored. The original tool call does not execute.
+If the user sends a normal follow-up message instead of answering, Ash keeps the session parked
+if the text doesn't match any pending option. If the text matches an option label (case-insensitive),
+it resolves as a structured response automatically.
 
 ## Configure Tool Approval In `tools/*.ts`
 
@@ -105,43 +106,40 @@ pending question for the client to surface to the user.
 
 ## Stream Behavior
 
-When HITL is needed, the run stream includes:
+When HITL is needed, the session stream includes:
 
 - `input.requested`
 - `session.waiting`
 
-`input.requested.data.requests` contains one or more runtime input requests. A batch may contain:
-
-- tool approval requests
-- user questions
-- or both
-
-Tool approval request shape:
+`input.requested.data.requests` contains one or more `InputRequest` objects. All requests share
+a single unified shape — tool approvals and questions use the same type:
 
 ```json
 {
-  "kind": "tool-approval",
-  "approvalId": "approval_123",
-  "toolName": "bash",
+  "requestId": "approval_123",
+  "prompt": "Approve tool call: bash",
+  "display": "confirmation",
+  "allowFreeform": false,
+  "options": [
+    { "id": "approve", "label": "Yes" },
+    { "id": "deny", "label": "No" }
+  ],
   "action": {
     "kind": "tool-call",
     "callId": "call_123",
     "toolName": "bash",
-    "input": {
-      "command": "rm -rf /tmp/demo"
-    }
+    "input": { "command": "rm -rf /tmp/demo" }
   }
 }
 ```
 
-Question request shape:
+Question request:
 
 ```json
 {
-  "kind": "question",
-  "toolName": "ask_question",
+  "requestId": "call_456",
   "prompt": "Which environment should I use?",
-  "allowFreeform": false,
+  "display": "select",
   "options": [
     { "id": "prod", "label": "Production" },
     { "id": "staging", "label": "Staging" }
@@ -161,6 +159,12 @@ Question request shape:
 }
 ```
 
+The `display` hint tells the client how to render:
+
+- `"confirmation"` — binary yes/no (buttons)
+- `"select"` — pick from a list (dropdown)
+- `"text"` — freeform input (text field)
+
 ## Respond Over HTTP
 
 Use the same `POST /.well-known/ash/v1/message` endpoint for HITL responses.
@@ -168,7 +172,7 @@ Use the same `POST /.well-known/ash/v1/message` endpoint for HITL responses.
 Allowed request bodies:
 
 ```json
-{ "message": "start a run" }
+{ "message": "start a session" }
 ```
 
 ```json
@@ -178,12 +182,8 @@ Allowed request bodies:
 ```json
 {
   "continuationToken": "<token>",
-  "inputResults": [
-    {
-      "kind": "tool-approval-result",
-      "approvalId": "approval_123",
-      "approved": true
-    }
+  "inputResponses": [
+    { "requestId": "approval_123", "optionId": "approve" }
   ]
 }
 ```
@@ -191,15 +191,8 @@ Allowed request bodies:
 ```json
 {
   "continuationToken": "<token>",
-  "inputResults": [
-    {
-      "kind": "question-result",
-      "callId": "call_456",
-      "output": {
-        "status": "answered",
-        "optionId": "prod"
-      }
-    }
+  "inputResponses": [
+    { "requestId": "call_456", "optionId": "prod" }
   ]
 }
 ```
@@ -210,30 +203,26 @@ You can also send both in one request:
 {
   "continuationToken": "<token>",
   "message": "Also, use the stricter settings.",
-  "inputResults": [
-    {
-      "kind": "tool-approval-result",
-      "approvalId": "approval_123",
-      "approved": true
-    }
+  "inputResponses": [
+    { "requestId": "approval_123", "optionId": "approve" }
   ]
 }
 ```
 
-## Ignore Or Bypass Pending Requests
-
-All HITL requests are optional.
+## Slack Behavior
 
-The user does not have to answer them. They can send a normal follow-up message instead.
+The Slack channel renders HITL requests as Block Kit interactive elements:
 
-When that happens:
+- **Approvals** → buttons (Yes / No)
+- **Questions with options** → static select menu
+- **Freeform questions** → prompt text (user replies in thread)
 
-- Ash marks the pending requests as ignored
-- a denied/ignored response is appended internally
-- the original tool call is not executed
-- the new user message becomes the next turn input
+When the user clicks a button or selects an option, the Slack interaction payload is
+automatically routed to the parked session. Text replies in the thread are resolved
+against the pending request options (case-insensitive label matching).
 
-This is the intended model. HITL requests are advisory pauses, not mandatory blockers.
+The Slack channel handles both Events API webhooks and interaction payloads at the same
+webhook URL — no separate interactivity endpoint needed.
 
 ## CLI Behavior
 
@@ -243,8 +232,7 @@ This is the intended model. HITL requests are advisory pauses, not mandatory blo
 - questions prompt for an option number or freeform answer
 - `Escape` returns to the normal `you>` prompt without answering
 
-If you press `Escape` and then send a normal message, the pending requests are ignored as described
-above.
+If you press `Escape` and then send a normal message, the pending requests are ignored.
 
 ## Current Limits
 

package/docs/public/migration-guide.md

@@ -0,0 +1,71 @@
+# Migration Guide
+
+Ash now has one durable authored-context model.
+
+## Breaking Changes
+
+- `getState(key)` is now `getContext(key)`.
+- `setState(key, value)` is now `setContext(key, value)`.
+- `ensureContext(key, valueOrFactory)` replaces `ContextKey({ initial })`.
+- `ContextKeyOptions.initial` was removed.
+- Public `ContextKey` values are session-durable by default.
+- `HarnessSession.state` is now split into `session.context` and internal `session.internal`.
+- Tool compaction hooks no longer return `sessionPatch`. Mutate durable context through `ctx` instead.
+
+## Before
+
+```ts
+import { ContextKey, getState, setState } from "experimental-ash";
+
+const NotesKey = new ContextKey("myapp.notes", {
+  initial: () => ({ notes: [] }),
+});
+
+setState(NotesKey, (current) => ({
+  notes: [...current.notes, "hello"],
+}));
+
+return getState(NotesKey);
+```
+
+## After
+
+```ts
+import { ContextKey, ensureContext, getContext, setContext } from "experimental-ash";
+
+const NotesKey = new ContextKey("myapp.notes");
+
+const current = ensureContext(NotesKey, () => ({ notes: [] }));
+
+setContext(NotesKey, {
+  notes: [...current.notes, "hello"],
+});
+
+return getContext(NotesKey);
+```
+
+## Channel Guidance
+
+- Use `channel.onDeliver(ctx, payload)` to seed or extend durable context on every turn.
+- Treat serialized channel state as immutable after the run starts.
+- Move mutable per-session data into durable context or `session.internal`, not onto the channel instance.
+
+## Compaction Hooks
+
+Before:
+
+```ts
+onCompact() {
+  return {
+    sessionPatch: { state: {} },
+  };
+}
+```
+
+After:
+
+```ts
+onCompact({ ctx }) {
+  ctx.set(NotesKey, { notes: [] });
+}
+```

package/docs/public/project-layout.md

@@ -16,6 +16,7 @@ my-agent/
     ├── system.md
     ├── system/
     ├── channels/
+    ├── connections/
     ├── skills/
     ├── lib/
     ├── sandboxes/
@@ -32,6 +33,7 @@ my-agent/
 | `system/` | Additive always-on prompt layers | Loaded in deterministic path order |
 | `agent.ts` | Runtime config | Model, name, metadata, workspace, build, compaction |
 | `channels/` | HTTP or messaging entrypoints | Root-only today |
+| `connections/` | External service connections (MCP) | Each file defines one connection; name derived from filename |
 | `skills/` | On-demand procedures and capability packs | Flat markdown, module-backed skills, or packaged skills |
 | `lib/` | Shared authored helper code | Import-only source, not mounted into the workspace |
 | `sandboxes/` | Isolated bash-style environments. Supports file form (`sandboxes/<name>.ts`) and folder form (`sandboxes/<name>/sandbox.ts` + optional `sandboxes/<name>/workspace/**`). | Supported on the root agent and local subagents |
@@ -50,6 +52,8 @@ agent/
 │   └── escalation-rules.md
 ├── channels/
 │   └── slack.ts
+├── connections/
+│   └── linear.ts
 ├── skills/
 │   ├── summarize.md
 │   └── research/
@@ -139,6 +143,7 @@ Use:
 - `system/` for additional always-on layers
 - `skills/` for optional procedures the model should load on demand
 - `tools/` for typed business logic and API calls
+- `connections/` for external services exposed via MCP (model discovers and calls their tools)
 - `sandboxes/` for isolated shell/file environments
 - `channels/` for HTTP or messaging ingress and delivery
 - `lib/` for shared helper modules imported by the slots above

package/docs/public/runs-and-streaming.md

@@ -1,20 +1,20 @@
-# Runs And Streaming
+# Sessions And Streaming
 
-Ash is durable and run-based by default.
+Ash is durable and session-based by default.
 
 The key client model is:
 
-- `POST /.well-known/ash/v1/message` starts a run or sends a follow-up
+- `POST /.well-known/ash/v1/message` starts a session or sends a follow-up
 - the response gives you a `continuationToken`
-- the response headers give you the `runId` for streaming
-- `GET /.well-known/ash/v1/runs/:runId/stream` lets you watch the run in real time
+- the response headers give you the `sessionId` for streaming
+- `GET /.well-known/ash/v1/sessions/:sessionId/stream` lets you watch the session in real time
 
 Ash keeps those separate on purpose:
 
 - channels own `continuationToken` as the resume handle
-- the runtime owns `runId` as the stream handle
+- the runtime owns `sessionId` as the stream handle
 
-## Start A Run
+## Start A Session
 
 ```bash
 curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
@@ -22,20 +22,21 @@ curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
   -d '{"message":"Summarize the latest forecast."}'
 ```
 
-Ash responds immediately. The JSON body includes a `continuationToken`, and the `x-ash-run-id`
-header identifies the durable run to stream.
+Ash responds immediately. The JSON body includes a `continuationToken`, and the
+`x-ash-session-id` header identifies the durable session to stream.
 
-## Stream A Run
+## Stream A Session
 
 ```bash
-curl http://127.0.0.1:3000/.well-known/ash/v1/runs/<runId>/stream
+curl http://127.0.0.1:3000/.well-known/ash/v1/sessions/<sessionId>/stream
 ```
 
 Common stream events:
 
-- `run.started`
+- `session.started`
 - `turn.started`
 - `message.received`
+- `step.started`
 - `sandbox.initialized`
 - `sandbox.restored`
 - `sandbox.command`
@@ -44,18 +45,19 @@ Common stream events:
 - `subagent.started`
 - `subagent.event`
 - `subagent.completed`
-- `thinking.completed`
+- `reasoning.completed`
 - `message.completed`
+- `step.completed`
 - `turn.completed`
 - `session.waiting`
-- `run.failed`
-- `run.completed`
+- `session.failed`
+- `session.completed`
 
 `message.completed` can appear more than once in a single turn when the agent
-produces an interim assistant message before making a tool call.
-Use `message.completed.data.finishReason` to distinguish interim tool-call
-steps from terminal assistant replies. `tool-calls` is non-terminal; other
-values are terminal for the current turn.
+produces interim assistant text before making a tool call.
+Use `message.completed.data.finishReason` to distinguish tool-call narration
+from terminal assistant replies. `step.completed.data.finishReason` mirrors the
+same step outcome, and usage lives on `step.completed`.
 
 ## Send A Follow-Up Message
 
@@ -73,21 +75,26 @@ curl -X POST http://127.0.0.1:3000/.well-known/ash/v1/message \
 The stream route accepts `startIndex` so clients can reconnect by event count:
 
 ```bash
-curl http://127.0.0.1:3000/.well-known/ash/v1/runs/<runId>/stream?startIndex=<count>
+curl http://127.0.0.1:3000/.well-known/ash/v1/sessions/<sessionId>/stream?startIndex=<count>
 ```
 
 ## The Execution Model
 
-Ash still runs one model turn at a time with durable state between turns. That is why tools,
-sandboxes, and subagents feel synchronous from authored code even though the overall run remains
-durable.
+Ash uses three nested concepts:
+
+- `session`: the whole durable conversation or task
+- `turn`: one user-visible roundtrip inside that session
+- `step`: one model call inside that turn
+
+That is why tools, sandboxes, and subagents feel synchronous from authored code even though the
+overall session remains durable.
 
 Important behavior:
 
 - follow-up messages reuse the same session through the continuation token
 - schedules do not wait for follow-up HTTP messages
-- subagent activity stays inline on the parent run stream rather than spawning a separate public
-  child-run stream
+- subagent activity stays inline on the parent session stream rather than spawning a separate public
+  child-session stream
 
 ## What To Read Next
 

package/docs/public/schedules.md

@@ -8,7 +8,7 @@ Schedules live under `schedules/` at the root agent package.
 
 - schedules are root-only today
 - local subagents cannot declare `schedules/`
-- schedule runs are task runs, not conversation runs
+- schedule sessions are task sessions, not conversation sessions
 
 ## Markdown Schedule Example
 
@@ -45,10 +45,10 @@ Ash compiles schedules into runtime-owned scheduled tasks.
 Important behavior:
 
 - the schedule id is derived from its path, for example `schedules/daily-digest`
-- the run goes through the same durable runtime engine as other task runs
+- the schedule session goes through the same durable runtime engine as other task sessions
 - schedule triggers always start the runtime in task mode, not conversation mode
-- top-level schedule runs do not wait for follow-up HTTP messages
-- if a scheduled task attempts to park for another user message, Ash fails the run instead of
+- top-level schedule sessions do not wait for follow-up HTTP messages
+- if a scheduled task attempts to park for another user message, Ash fails the session instead of
   silently completing it
 - `getSession().auth.current` and `getSession().auth.initiator` are both set to a framework-owned
   `schedule` principal