experimental-ash 0.16.0 → 0.16.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # experimental-ash
 
+## 0.16.1
+
+### Patch Changes
+
+- 8cf749c: Expose the clicking actor as a `user` field on `SlackInteractionAction` so `onInteraction` handlers can attribute resolutions without re-parsing the raw payload.
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/docs/public/agent-ts.md

@@ -33,11 +33,13 @@ Use `agent.ts` for:
 
 - model selection
 - metadata you want preserved in runtime traces
-- human-in-the-loop policy
 - hosted-build packaging controls
 - compaction settings
 - provider-specific model options
 
+Per-tool approval (formerly "human-in-the-loop policy") lives on each tool via `needsApproval`,
+not in `agent.ts`. See [Human In The Loop](./human-in-the-loop.md).
+
 For OpenTelemetry configuration, use `instrumentation.ts` instead. See
 [`instrumentation.ts`](./instrumentation.md).
 
@@ -130,29 +132,10 @@ server output instead of being bundled.
 The shared per-run workspace is configured on the sandbox, not on `agent.ts`. See
 [Workspace](./workspace.md) and [Sandboxes](./sandbox.md).
 
-## `humanInTheLoop`
-
-`humanInTheLoop` controls whether Ash should pause for approval before executing model-visible
-tools.
-
-```ts
-export default defineAgent({
-  humanInTheLoop: {
-    mode: "require-approval",
-  },
-});
-```
-
-Supported fields:
-
-- `mode: "require-approval" | "auto-allow"`
-- `allow?: readonly string[]`
-- `ask?: readonly string[]`
-
-Use `require-approval` when the default should be "ask first". Use `auto-allow` when the default
-should be "run immediately" and only a few named tools should still require approval.
+## Human In The Loop
 
-See [Human In The Loop](./human-in-the-loop.md) for the runtime flow, `input.requested`
+Approval policy lives on individual tools via `needsApproval` in `defineTool({...})`, not on
+`agent.ts`. See [Human In The Loop](./human-in-the-loop.md) for the runtime flow, `input.requested`
 events, and HTTP response payloads.
 
 ## Telemetry

package/dist/docs/public/context-control.md

@@ -66,7 +66,6 @@ Use the weather tool before answering forecast or temperature questions.
 
 ```md
 ---
-name: research
 description: Research unfamiliar topics before answering with confidence.
 ---
 
@@ -84,7 +83,8 @@ prompt.
 ### Skill Rules That Matter
 
 - packaged `SKILL.md` files must include YAML frontmatter
-- `name` and `description` are required in packaged skill frontmatter
+- `description` is required in packaged skill frontmatter; identity is derived from the directory
+  name
 - flat markdown skills may omit frontmatter
 - tools stay visible whether or not a skill is activated
 

package/dist/docs/public/evals.md

@@ -39,9 +39,7 @@ import { defineEvalSuite } from "experimental-ash/evals";
 import { Run } from "experimental-ash/evals/scores";
 
 export default defineEvalSuite({
-  id: "weather-smoke",
   model: "openai/gpt-5.4-mini",
-  name: "Weather Smoke",
   description: "Basic message and tool-usage coverage for the weather agent.",
   cases: [
     {
@@ -55,13 +53,12 @@ export default defineEvalSuite({
 ```
 
 `defineEvalSuite(...)` validates the suite shape and returns a normalized suite object that the CLI
-can discover and run.
+can discover and run. Suite identity is derived from the `.eval.ts` file path — authored
+definitions do not carry an `id` or `name`.
 
 Every suite must provide:
 
-- `id`
 - `model`
-- `name`
 - `scores`
 - either `cases` or `load`
 
@@ -88,9 +85,7 @@ You can provide cases directly:
 
 ```ts
 export default defineEvalSuite({
-  id: "smoke",
   model: "openai/gpt-5.4-mini",
-  name: "Smoke",
   cases: [
     {
       id: "hello",
@@ -110,9 +105,7 @@ import { loadYaml } from "experimental-ash/evals/loaders";
 import { Text } from "experimental-ash/evals/scores";
 
 export default defineEvalSuite({
-  id: "marketing-sql",
   model: "openai/gpt-5.4-mini",
-  name: "Marketing SQL",
   async load() {
     const doc = await loadYaml("evals/data/cases.yaml");
     return (doc.evals as readonly { task: string; prompt: string; sql: string }[]).map((row) => ({
@@ -131,9 +124,7 @@ message.
 
 ```ts
 defineEvalSuite({
-  id: "weather-task",
   model: "openai/gpt-5.4-mini",
-  name: "Weather Task",
   task: {
     prompt: (testCase) => `Answer the user: ${String(testCase.input)}`,
     parseOutput: (result) => result.finalMessage,
@@ -149,9 +140,7 @@ Suite thresholds let you relax a scorer from the default exact-match requirement
 
 ```ts
 defineEvalSuite({
-  id: "weather",
   model: "openai/gpt-5.4-mini",
-  name: "Weather",
   cases: [{ id: "hello", input: "Hello", expected: "Hello" }],
   scores: [Run.didNotFail(), Text.includes()],
   thresholds: {
@@ -180,8 +169,6 @@ import { defineEvalSuite } from "experimental-ash/evals";
 import { Autoevals, Run } from "experimental-ash/evals/scores";
 
 export default defineEvalSuite({
-  id: "support-quality",
-  name: "Support Quality",
   model: "openai/gpt-5.4-mini",
   cases: [{ id: "refund", input: "How do I get a refund?", expected: "refund policy" }],
   scores: [Run.didNotFail(), Autoevals.factuality()],

package/dist/docs/public/project-layout.md

@@ -34,7 +34,7 @@ my-agent/
 | Path                                   | Purpose                                                                                                                                                                                                                                | Notes                                                                                                                                                                                                                                           |
 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `instructions.md` or `instructions.ts` | Base instructions prompt                                                                                                                                                                                                               | Exactly one instructions prompt is expected. Module-backed sources execute once at build time; the resulting markdown is baked into the compiled manifest. The legacy `system.{md,ts,...}` slot is still discovered with a deprecation warning. |
-| `agent.ts`                             | Runtime config                                                                                                                                                                                                                         | Model, metadata, workspace, build, compaction                                                                                                                                                                                                   |
+| `agent.ts`                             | Runtime config                                                                                                                                                                                                                         | Model, metadata, build, compaction, modelOptions                                                                                                                                                                                                |
 | `instrumentation.ts`                   | Telemetry config                                                                                                                                                                                                                       | OTel exporter setup and AI SDK span settings; auto-discovered and run before agent code                                                                                                                                                         |
 | `channels/`                            | HTTP or messaging entrypoints                                                                                                                                                                                                          | Root-only today                                                                                                                                                                                                                                 |
 | `connections/`                         | External service connections (MCP)                                                                                                                                                                                                     | Each file defines one connection; name derived from filename                                                                                                                                                                                    |

package/dist/docs/public/skills.md

@@ -45,7 +45,7 @@ The smallest skill is just a markdown file.
 Use the weather tool before answering forecast or temperature questions.
 ```
 
-For flat skills, Ash derives the skill id and name from the file path.
+For flat skills, Ash derives the skill id from the file path.
 
 You can also add frontmatter when you want to control the description explicitly:
 
@@ -63,7 +63,6 @@ Use a packaged skill when the procedure needs sibling files.
 
 ```md
 ---
-name: research
 description: Research unfamiliar topics before answering with confidence.
 ---
 
@@ -99,7 +98,8 @@ export default defineTool({
 
 - flat skills can be simple markdown files under `skills/*.md`
 - packaged skills live under `skills/<name>/SKILL.md`
-- packaged `SKILL.md` files must include `name` and `description` frontmatter
+- packaged `SKILL.md` files must include `description` frontmatter; skill identity is derived from
+  the directory name
 - flat skills may omit frontmatter
 
 ## Write Good Descriptions
@@ -145,7 +145,6 @@ If markdown is not enough, you can author a skill in TypeScript with `defineSkil
 import { defineSkill } from "experimental-ash/skills";
 
 export default defineSkill({
-  name: "research",
   description: "Research unfamiliar topics before answering with confidence.",
   markdown:
     "When the task is novel or ambiguous, gather evidence first, then answer with the key facts and the remaining uncertainty.",

package/dist/docs/public/subagents.md

@@ -106,7 +106,7 @@ Child `session.started.data.invocation` includes the parent call/session/turn li
 
 Local subagents may have their own:
 
-- `system`
+- `instructions.md` or `instructions.ts`
 - `skills/`
 - `lib/`
 - `tools/`

package/dist/docs/public/tools.md

@@ -263,7 +263,6 @@ unbounded text, cap it in the executor before returning:
 
 ```ts
 import { defineTool } from "experimental-ash/tools";
-import { truncateHead } from "experimental-ash/sandbox/truncate-output";
 import { z } from "zod";
 
 export default defineTool({

package/dist/docs/public/typescript-api.md

@@ -20,8 +20,9 @@ Source of truth:
 Use these to author the filesystem-backed surface. Each concern has its own subpath:
 `experimental-ash/tools` for tools, `experimental-ash/hooks` for hooks,
 `experimental-ash/sandbox` for the sandbox, `experimental-ash/skills` for skills,
-`experimental-ash/context` for context helpers, and the main `experimental-ash`
-barrel for agent config, schedules, and systems.
+`experimental-ash/schedules` for schedules, `experimental-ash/instructions` for the instructions
+prompt, `experimental-ash/context` for context helpers, and the main `experimental-ash` barrel
+for `defineAgent`.
 
 - `defineAgent(...)` - additive runtime config for `agent.ts`. Subagents reuse the same helper at
   `subagents/<id>/agent.ts`; the only difference is that subagents must declare a `description` so
@@ -41,7 +42,7 @@ barrel for agent config, schedules, and systems.
 
 Framework defaults reachable for spread/wrap composition:
 
-- `bash`, `readFile`, `writeFile`, `webFetch`, `todo`, `loadSkill` (`experimental-ash/tools/defaults`)
+- `bash`, `glob`, `grep`, `readFile`, `writeFile`, `webFetch`, `webSearch`, `todo`, `loadSkill` (`experimental-ash/tools/defaults`)
 
 Most apps use `defineAgent`, `defineTool`, and `defineSandbox` the most.
 

package/dist/src/internal/application/package.js

@@ -6,7 +6,7 @@ import { ASH_PACKAGE_NAME } from "#package-name.js";
 let cachedPackageInfo;
 // The package build stamps the published version into `dist` so bundled
 // deployments can still report package metadata without resolving package.json.
-const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.16.0";
+const BUNDLED_FALLBACK_PACKAGE_VERSION = "0.16.1";
 const BUNDLED_FALLBACK_PACKAGE_VERSION_PLACEHOLDER = "__ASH_PACKAGE_VERSION_PLACEHOLDER__";
 const WORKFLOW_MODULE_ALIASES = {
     "workflow/api": "src/compiled/@workflow/core/runtime.js",

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

@@ -27,11 +27,6 @@ interface ParsedBlockActionsPayload {
     readonly channelId: string;
     readonly threadTs: string;
     readonly teamId: string | undefined;
-    /**
-     * Slack actor that authored the click. Used to attribute the answered
-     * card via `Answered by <@userId>` after a HITL response is delivered.
-     */
-    readonly userId: string | undefined;
     /**
      * The full block list off the clicked message. Preserved on the
      * answered-card update so the original prompt stays visible after the

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

@@ -29,30 +29,37 @@ export function parseBlockActionsPayload(body) {
     const actions = body.actions;
     if (!Array.isArray(actions))
         return null;
+    // `channel` and `message` are Optional on block_actions payloads — only
+    // present when the action was triggered from a message in a channel.
     const channel = body.channel?.id;
     const message = body.message;
     const threadTs = message?.thread_ts ?? message?.ts;
     if (!channel || !threadTs)
         return null;
+    // `team` is Required but can be `null` for org-installed apps.
+    // `user` is Required and always carries `id`.
     const team = body.team;
-    const user = body.user;
-    const teamId = team?.id ?? user?.team_id;
-    const userId = typeof user?.id === "string" ? user.id : undefined;
-    const messageTs = typeof message?.ts === "string" ? message.ts : undefined;
-    const messageBlocks = Array.isArray(message?.blocks) ? message.blocks : [];
+    const userBlock = body.user;
+    const teamId = team?.id ?? userBlock.team_id;
+    const user = {
+        id: userBlock.id,
+        username: userBlock.username,
+        name: userBlock.name,
+    };
+    const messageBlocks = message?.blocks ?? [];
     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,
             selectedOptionValue: extractSelectedOptionValue(a),
-            messageTs,
+            messageTs: message?.ts,
             label: extractActionLabel(a),
+            user,
         })),
         channelId: channel,
         threadTs,
         teamId,
-        userId,
         messageBlocks,
     };
 }
@@ -130,7 +137,7 @@ export async function handleInteractionPost(rawBody, ctx, deps) {
                 channelId: interaction.channelId,
                 threadTs: interaction.threadTs,
                 teamId: interaction.teamId ?? null,
-                triggeringUserId: interaction.userId ?? null,
+                triggeringUserId: interaction.actions[0]?.user.id ?? null,
             },
         })
             .catch((error) => {
@@ -222,9 +229,11 @@ async function handleViewSubmission(payload, ctx, _deps) {
     const text = typeof raw === "string" ? raw : "";
     if (text.length === 0)
         return ack;
+    // `user` is Required on view_submission payloads; `team_id` is on the
+    // user object in modern payloads but not guaranteed in all examples.
     const user = payload.user;
-    const triggeringUserId = typeof user?.id === "string" ? user.id : null;
-    const teamId = typeof user?.team_id === "string" ? user.team_id : null;
+    const triggeringUserId = user.id;
+    const teamId = user.team_id ?? null;
     ctx.waitUntil(ctx
         .send({ inputResponses: [{ requestId: metadata.requestId, text }] }, {
         auth: null,
@@ -260,7 +269,7 @@ async function updateAnsweredHitlCard(interaction, deps) {
     const blocks = buildAnsweredBlocks({
         promptBlock: findPromptBlock(interaction.messageBlocks),
         answerLabel,
-        userId: interaction.userId,
+        userId: hitlAction.user.id,
     });
     const token = await resolveSlackBotToken(deps.config.credentials?.botToken);
     const response = await fetch("https://slack.com/api/chat.update", {

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

@@ -117,6 +117,24 @@ export interface SlackInteractionAction {
      * the "answered" card without re-fetching the original request.
      */
     readonly label?: string;
+    /**
+     * Slack actor who triggered the interaction. Lets `onInteraction`
+     * handlers attribute resolutions back to the clicker (e.g. "Filed by
+     * <@U0123456789>") without re-parsing the raw payload. Always present
+     * — Slack requires `user` on every `block_actions` payload.
+     */
+    readonly user: SlackInteractionUser;
+}
+/**
+ * Slack actor surfaced on {@link SlackInteractionAction.user}. Mirrors
+ * `body.user` from the inbound `block_actions` payload.
+ */
+export interface SlackInteractionUser {
+    readonly id: string;
+    /** Modern canonical display handle. */
+    readonly username?: string;
+    /** Legacy display handle, kept for older workspaces. */
+    readonly name?: string;
 }
 /**
  * Result of an `onAppMention` or `onDirectMessage` callback. Return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"