experimental-ash 0.20.1 → 0.22.0

package/dist/src/public/tool-result-narrowing.js

@@ -0,0 +1,58 @@
+const DEFINITION_SOURCE = Symbol("ash.definitionSource");
+/**
+ * Stamps the path-derived runtime name onto an authored definition
+ * object as a non-enumerable symbol property.
+ *
+ * Called by the resolution pipeline (`resolveToolDefinition`,
+ * `resolveConnectionDefinition`) so {@link toolResultFrom} can read
+ * the name back without a separate lookup structure.
+ */
+export function stampDefinitionSource(definition, entry) {
+    Object.defineProperty(definition, DEFINITION_SOURCE, { value: entry });
+}
+function readDefinitionSource(definition) {
+    if (DEFINITION_SOURCE in definition) {
+        return definition[DEFINITION_SOURCE];
+    }
+    return undefined;
+}
+const CONNECTION_TOOL_SEPARATOR = "__";
+/**
+ * Narrows a {@link RuntimeActionResult} to a typed tool or connection
+ * result by matching against an authored definition object.
+ *
+ * Pass a `ToolDefinition` to get a typed `output`; pass a
+ * `McpClientConnectionDefinition` to match any tool from that
+ * connection (`output` stays `unknown`).
+ *
+ * Returns `undefined` when the result doesn't match, or when
+ * `isError` is `true`.
+ */
+export const toolResultFrom = toolResultFromImpl;
+function toolResultFromImpl(result, source) {
+    if (result.kind !== "tool-result")
+        return undefined;
+    if (result.isError === true)
+        return undefined;
+    const entry = readDefinitionSource(source);
+    if (entry === undefined)
+        return undefined;
+    if (entry.kind === "tool") {
+        if (result.toolName !== entry.name)
+            return undefined;
+        return {
+            callId: result.callId,
+            output: result.output,
+            toolName: result.toolName,
+        };
+    }
+    const prefix = entry.name + CONNECTION_TOOL_SEPARATOR;
+    if (!result.toolName.startsWith(prefix))
+        return undefined;
+    return {
+        callId: result.callId,
+        connectionToolName: result.toolName.slice(prefix.length),
+        output: result.output,
+        toolName: result.toolName,
+    };
+}

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

@@ -2,6 +2,7 @@
  * Tool authoring helpers for `agent/tools/*.ts` files.
  */
 export { type CompactionHookInput, type CompactionHookResult, type DisabledToolSentinel, defineTool, disableTool, isDisabledToolSentinel, type NeedsApprovalContext, type RetentionSummary, type ToolDefinition, type ToolModelOutput, type ToolRetentionPolicy, } from "#public/definitions/tool.js";
+export { toolResultFrom, type MatchedConnectionResult, type MatchedToolResult, type ToolResultFromFn, } from "#public/tool-result-narrowing.js";
 export { type DefineBashToolInput, defineBashTool } from "#public/tools/define-bash-tool.js";
 export { type DefineGlobToolInput, defineGlobTool } from "#public/tools/define-glob-tool.js";
 export { type DefineGrepToolInput, defineGrepTool } from "#public/tools/define-grep-tool.js";

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

@@ -2,6 +2,7 @@
  * Tool authoring helpers for `agent/tools/*.ts` files.
  */
 export { defineTool, disableTool, isDisabledToolSentinel, } from "#public/definitions/tool.js";
+export { toolResultFrom, } from "#public/tool-result-narrowing.js";
 export { defineBashTool } from "#public/tools/define-bash-tool.js";
 export { defineGlobTool } from "#public/tools/define-glob-tool.js";
 export { defineGrepTool } from "#public/tools/define-grep-tool.js";

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

@@ -1,4 +1,5 @@
 import { expectObjectRecord } from "#internal/authored-module.js";
+import { stampDefinitionSource } from "#public/tool-result-narrowing.js";
 import { toErrorMessage } from "#shared/errors.js";
 import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
 import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
@@ -22,6 +23,7 @@ export async function resolveConnectionDefinition(definition, moduleMap, nodeId)
             nodeId,
         });
         const resolvedRecord = expectObjectRecord(resolvedExportValue, `Expected the connection export "${definition.exportName ?? "default"}" from "${definition.logicalPath}" to return an object.`);
+        stampDefinitionSource(resolvedRecord, { kind: "connection", name: definition.connectionName });
         const hasAuth = resolvedRecord.auth !== undefined;
         const hasHeaders = resolvedRecord.headers !== undefined;
         const result = {

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

@@ -1,4 +1,5 @@
 import { expectFunction, expectObjectRecord } from "#internal/authored-module.js";
+import { stampDefinitionSource } from "#public/tool-result-narrowing.js";
 import { toErrorMessage } from "#shared/errors.js";
 import { loadResolvedModuleExport, ResolveAgentError } from "#runtime/resolve-helpers.js";
 /**
@@ -20,6 +21,7 @@ export async function resolveToolDefinition(definition, moduleMap, nodeId) {
             nodeId,
         });
         const resolvedRecord = expectObjectRecord(resolvedExportValue, describe(definition, "to return an object"));
+        stampDefinitionSource(resolvedRecord, { kind: "tool", name: definition.name });
         const execute = expectFunction(resolvedRecord.execute, describe(definition, "to provide an execute function"));
         return {
             description: definition.description,

package/dist/src/shared/skill-definition.d.ts

@@ -1,7 +1,25 @@
-export interface InternalSkillDefinition {
-    name: string;
+/**
+ * File payload accepted for authored or runtime-created skill package
+ * siblings. Strings are written as UTF-8; bytes are preserved exactly.
+ */
+export type SkillFileContent = string | Uint8Array;
+/**
+ * Public skill package content shared by TypeScript-authored skills and
+ * runtime hook contributions.
+ */
+export interface SkillPackageDefinition {
     description: string;
     license?: string;
     markdown: string;
     metadata?: Record<string, string>;
+    files?: Readonly<Record<string, SkillFileContent>>;
+}
+/**
+ * Runtime-contributed skill package. Hook-created skills do not have an
+ * authored file path, so they carry their name explicitly.
+ */
+export interface NamedSkillDefinition extends SkillPackageDefinition {
+    name: string;
+}
+export interface InternalSkillDefinition extends NamedSkillDefinition {
 }

package/dist/src/shared/skill-package.d.ts

@@ -0,0 +1,43 @@
+import { Buffer } from "node:buffer";
+import type { SandboxSession } from "#shared/sandbox-session.js";
+import type { NamedSkillDefinition } from "#shared/skill-definition.js";
+export interface NormalizedSkillPackageFile {
+    readonly content: Buffer;
+    readonly relativePath: string;
+}
+export interface MaterializableSkillPackage {
+    readonly description: string;
+    readonly files: readonly NormalizedSkillPackageFile[];
+    readonly license?: string;
+    readonly markdown: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly name: string;
+}
+/**
+ * Normalizes one named skill package into the concrete files Ash writes to
+ * workspace resources or the live sandbox.
+ */
+export declare function normalizeSkillPackage(input: NamedSkillDefinition): MaterializableSkillPackage;
+/**
+ * Writes a normalized package under a compiled workspace resource node root.
+ *
+ * For a `rootPath` of `.ash/compile/workspace-resources/__root__` and a skill
+ * named `research`, files land under `skills/research/`.
+ */
+export declare function writeSkillPackageDirectory(input: {
+    readonly rootPath: string;
+    readonly skill: MaterializableSkillPackage;
+}): Promise<void>;
+/**
+ * Writes a normalized package into the live sandbox under
+ * `/workspace/skills/<name>/`.
+ */
+export declare function writeSkillPackageToSandbox(input: {
+    readonly sandbox: SandboxSession;
+    readonly skill: MaterializableSkillPackage;
+}): Promise<void>;
+/**
+ * Validates a runtime-contributed skill name before it becomes one path
+ * segment under `/workspace/skills`.
+ */
+export declare function assertSafeSkillPackageName(name: string): void;

package/dist/src/shared/skill-package.js

@@ -0,0 +1,100 @@
+import { Buffer } from "node:buffer";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const WORKSPACE_ROOT = "/workspace";
+/**
+ * Normalizes one named skill package into the concrete files Ash writes to
+ * workspace resources or the live sandbox.
+ */
+export function normalizeSkillPackage(input) {
+    assertSafeSkillPackageName(input.name);
+    const files = [
+        {
+            content: Buffer.from(input.markdown, "utf8"),
+            relativePath: "SKILL.md",
+        },
+    ];
+    for (const [relativePath, content] of Object.entries(input.files ?? {})) {
+        assertSafeSkillPackageFilePath(relativePath);
+        files.push({
+            content: contentToBuffer(content),
+            relativePath,
+        });
+    }
+    files.sort((left, right) => comparePaths(left.relativePath, right.relativePath));
+    return {
+        description: input.description,
+        files,
+        license: input.license,
+        markdown: input.markdown,
+        metadata: input.metadata === undefined ? undefined : { ...input.metadata },
+        name: input.name,
+    };
+}
+/**
+ * Writes a normalized package under a compiled workspace resource node root.
+ *
+ * For a `rootPath` of `.ash/compile/workspace-resources/__root__` and a skill
+ * named `research`, files land under `skills/research/`.
+ */
+export async function writeSkillPackageDirectory(input) {
+    for (const file of input.skill.files) {
+        const filePath = join(input.rootPath, "skills", input.skill.name, file.relativePath);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, file.content);
+    }
+}
+/**
+ * Writes a normalized package into the live sandbox under
+ * `/workspace/skills/<name>/`.
+ */
+export async function writeSkillPackageToSandbox(input) {
+    for (const file of input.skill.files) {
+        await input.sandbox.writeBinaryFile({
+            content: file.content,
+            path: `${WORKSPACE_ROOT}/skills/${input.skill.name}/${file.relativePath}`,
+        });
+    }
+}
+/**
+ * Validates a runtime-contributed skill name before it becomes one path
+ * segment under `/workspace/skills`.
+ */
+export function assertSafeSkillPackageName(name) {
+    if (name.length === 0 ||
+        name.trim() !== name ||
+        name.startsWith(".") ||
+        name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("..") ||
+        /^[A-Za-z]:/.test(name)) {
+        throw new Error('Expected skill name to be a non-empty safe path segment without whitespace, separators, "." prefix, or "..".');
+    }
+}
+function assertSafeSkillPackageFilePath(relativePath) {
+    if (relativePath === "SKILL.md") {
+        throw new Error('Skill package files must not include "SKILL.md"; Ash generates it.');
+    }
+    if (relativePath.length === 0 ||
+        relativePath.startsWith("/") ||
+        relativePath.includes("\\") ||
+        /^[A-Za-z]:/.test(relativePath) ||
+        relativePath
+            .split("/")
+            .some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+        throw new Error("Expected skill package file paths to be relative POSIX paths.");
+    }
+}
+function contentToBuffer(content) {
+    if (typeof content === "string") {
+        return Buffer.from(content, "utf8");
+    }
+    return Buffer.from(content);
+}
+function comparePaths(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-ash",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "bin": {
     "ash": "./bin/ash.js",
     "experimental-ash": "./bin/ash.js"
@@ -41,6 +41,11 @@
       "import": "./dist/src/react/index.js",
       "default": "./dist/src/react/index.js"
     },
+    "./next": {
+      "types": "./dist/src/public/next/index.d.ts",
+      "import": "./dist/src/public/next/index.js",
+      "default": "./dist/src/public/next/index.js"
+    },
     "./tools/approval": {
       "types": "./dist/src/public/tools/approval/index.d.ts",
       "import": "./dist/src/public/tools/approval/index.js",
@@ -156,9 +161,9 @@
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "4.0.0-canary.57",
-    "@ai-sdk/google": "4.0.0-canary.67",
+    "@ai-sdk/google": "4.0.0-canary.69",
     "@ai-sdk/mcp": "2.0.0-canary.52",
-    "@ai-sdk/openai": "4.0.0-canary.61",
+    "@ai-sdk/openai": "4.0.0-canary.62",
     "@ai-sdk/otel": "1.0.0-canary.90",
     "@ai-sdk/provider": "4.0.0-canary.17",
     "@chat-adapter/slack": "4.28.1",
@@ -181,6 +186,7 @@
     "jose": "6.2.3",
     "jsonc-parser": "3.3.1",
     "just-bash": "2.14.5",
+    "next": "^16.2.6",
     "picocolors": "^1.1.1",
     "react": "^19.2.6",
     "react-test-renderer": "19.2.6",
@@ -192,6 +198,7 @@
     "@opentelemetry/api": "^1.9.0",
     "ai": "7.0.0-canary.144",
     "braintrust": ">=3.0.0",
+    "next": "^16.2.6",
     "react": "^19.2.6"
   },
   "peerDependenciesMeta": {
@@ -201,6 +208,9 @@
     "braintrust": {
       "optional": true
     },
+    "next": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }