experimental-agent 0.3.0 → 0.4.0

package/README.md

@@ -23,6 +23,22 @@ import { agent } from "experimental-agent";
 export const myAgent = agent("my-agent", {
   model: "anthropic/claude-opus-4.6",
   system: "You are a helpful coding assistant.",
+  skills: [
+    { type: "sandbox", path: ".agent/skills/project" },
+    { type: "host", path: "./skills/company" },
+    {
+      type: "git",
+      repo: "https://github.com/acme/agent-skills.git",
+      ref: "v1.2.0",
+      path: "skills",
+    },
+    {
+      type: "inline",
+      name: "incident-triage",
+      description: "Triage incidents safely",
+      instructions: "1. Gather context\n2. Confirm blast radius\n3. Propose mitigations",
+    },
+  ],
 });
 ```
 
@@ -111,6 +127,50 @@ agent("my-agent", {
 
 The SDK stores `Session`, `Message`, `Part`, `Sandbox`. Everything else — users, titles, access control — belongs in your database. Session ID is your join key.
 
+## Skills
+
+`skills` is the canonical skills API for both `agent(...)` defaults and `session.update(...)` overrides.
+
+- `{ type: "sandbox", path: "..." }` reads skills already present in sandbox
+- `{ type: "host", path: "..." }` copies skills from host filesystem into sandbox materialized dirs
+- `{ type: "git", ... }` clones a git repo into sandbox materialized dirs (optionally with `ref`, `path`, `name`)
+- `{ type: "inline", ... }` writes an inline `SKILL.md` into sandbox materialized dirs
+
+```ts
+const session = myAgent.session("chat-123");
+
+await session.update({
+  skills: [
+    {
+      type: "git",
+      repo: "https://github.com/acme/agent-skills.git",
+      ref: "main",
+      path: "skills",
+      name: "release-playbook",
+    },
+  ],
+});
+```
+
+### Migration
+
+Legacy `skillsDir` configuration is deprecated. Migrate to `skills`:
+
+```ts
+// before
+agent("my-agent", {
+  skillsDir: [".agent/skills", ".agent/skills/shared"],
+});
+
+// after
+agent("my-agent", {
+  skills: [
+    { type: "sandbox", path: ".agent/skills" },
+    { type: "sandbox", path: ".agent/skills/shared" },
+  ],
+});
+```
+
 ## Documentation
 
 Full docs at [packages/agent/docs](./docs/).
@@ -125,3 +185,4 @@ pnpm test         # vitest run
 pnpm test:watch   # vitest watch
 pnpm typecheck    # tsc --noEmit
 ```
+

package/dist/{adapter-BigchkkI.d.mts → adapter-zgOel4wW.d.mts}

@@ -2,6 +2,68 @@ import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 import { NetworkPolicy } from '@vercel/sandbox';
 import { UIMessage } from 'ai';
 
+type SkillSourceType = "sandbox" | "host" | "git" | "inline";
+type SandboxSkillInput = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillInput = {
+    type: "host";
+    path: string;
+};
+type GitSkillInput = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillInput = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillInput = SandboxSkillInput | HostSkillInput | GitSkillInput | InlineSkillInput;
+type SandboxSkillEntry = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillEntry = {
+    type: "host";
+    path: string;
+};
+type GitSkillEntry = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillEntry = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillEntry = SandboxSkillEntry | HostSkillEntry | GitSkillEntry | InlineSkillEntry;
+
+type GenerationOptions = {
+    maxSteps?: number;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    maxOutputTokens?: number;
+    headers?: Record<string, string>;
+};
 type Session = {
     id: string;
     createdAt: number;
@@ -11,17 +73,30 @@ type Session = {
     sandboxId: string | null;
     lastMessageId: string | null;
     activeTools: string[] | null;
-    skillsDir: string[] | null;
-    generation: {
-        maxSteps?: number;
-        temperature?: number;
-        topK?: number;
-        topP?: number;
-        frequencyPenalty?: number;
-        presencePenalty?: number;
-        maxOutputTokens?: number;
-        headers?: Record<string, string>;
-    } | null;
+    skills: SkillInput[] | null;
+    generation: GenerationOptions | null;
+};
+type MessageUsage = {
+    steps: {
+        stepIndex: number;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens: number;
+    }[];
+    summary: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens: number;
+        stepCount: number;
+    };
 };
 type Message = {
     id: string;
@@ -35,29 +110,9 @@ type Message = {
         index: number;
         part: unknown;
     } | null;
-    usage: {
-        steps: {
-            stepIndex: number;
-            model: string;
-            inputTokens: number;
-            outputTokens: number;
-            totalTokens: number;
-            cacheReadTokens: number;
-            cacheWriteTokens: number;
-            reasoningTokens: number;
-        }[];
-        summary: {
-            model: string;
-            inputTokens: number;
-            outputTokens: number;
-            totalTokens: number;
-            cacheReadTokens: number;
-            cacheWriteTokens: number;
-            reasoningTokens: number;
-            stepCount: number;
-        };
-    } | null;
+    usage: MessageUsage | null;
     workflowRunId?: string | null;
+    metadata?: Record<string, unknown> | null;
 };
 type Part = {
     id: string;
@@ -198,4 +253,4 @@ interface Storage {
 type StorageInput = StorageHandlers | StorageStepFunction;
 declare function toStorage(h: StorageInput): Storage;
 
-export { type Message as M, type Part as P, type StorageHandlers as S, type Sandbox as a, type Session as b, type Setup as c, type SetupSnapshot as d, type Storage as e, type StorageCall as f, StorageStep as g, type StorageStepFunction as h, type StorageInput as i, toStorage as t };
+export { type GenerationOptions as G, type HostSkillEntry as H, type InlineSkillEntry as I, type Message as M, type Part as P, type StorageHandlers as S, type MessageUsage as a, type Sandbox as b, type Session as c, type Setup as d, type SetupSnapshot as e, type Storage as f, type StorageCall as g, StorageStep as h, type StorageStepFunction as i, type SkillInput as j, type StorageInput as k, type GitSkillEntry as l, type GitSkillInput as m, type HostSkillInput as n, type InlineSkillInput as o, type SandboxSkillEntry as p, type SandboxSkillInput as q, type SkillEntry as r, type SkillSourceType as s, toStorage as t };

package/dist/{adapter-BigchkkI.d.ts → adapter-zgOel4wW.d.ts}

@@ -2,6 +2,68 @@ import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@workflow/serde';
 import { NetworkPolicy } from '@vercel/sandbox';
 import { UIMessage } from 'ai';
 
+type SkillSourceType = "sandbox" | "host" | "git" | "inline";
+type SandboxSkillInput = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillInput = {
+    type: "host";
+    path: string;
+};
+type GitSkillInput = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillInput = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillInput = SandboxSkillInput | HostSkillInput | GitSkillInput | InlineSkillInput;
+type SandboxSkillEntry = {
+    type: "sandbox";
+    path: string;
+};
+type HostSkillEntry = {
+    type: "host";
+    path: string;
+};
+type GitSkillEntry = {
+    type: "git";
+    repo: string;
+    ref?: string;
+    path?: string;
+    /**
+     * Skill directory name under `path`.
+     */
+    name?: string;
+};
+type InlineSkillEntry = {
+    type: "inline";
+    name: string;
+    description: string;
+    instructions: string;
+};
+type SkillEntry = SandboxSkillEntry | HostSkillEntry | GitSkillEntry | InlineSkillEntry;
+
+type GenerationOptions = {
+    maxSteps?: number;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    maxOutputTokens?: number;
+    headers?: Record<string, string>;
+};
 type Session = {
     id: string;
     createdAt: number;
@@ -11,17 +73,30 @@ type Session = {
     sandboxId: string | null;
     lastMessageId: string | null;
     activeTools: string[] | null;
-    skillsDir: string[] | null;
-    generation: {
-        maxSteps?: number;
-        temperature?: number;
-        topK?: number;
-        topP?: number;
-        frequencyPenalty?: number;
-        presencePenalty?: number;
-        maxOutputTokens?: number;
-        headers?: Record<string, string>;
-    } | null;
+    skills: SkillInput[] | null;
+    generation: GenerationOptions | null;
+};
+type MessageUsage = {
+    steps: {
+        stepIndex: number;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens: number;
+    }[];
+    summary: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens: number;
+        stepCount: number;
+    };
 };
 type Message = {
     id: string;
@@ -35,29 +110,9 @@ type Message = {
         index: number;
         part: unknown;
     } | null;
-    usage: {
-        steps: {
-            stepIndex: number;
-            model: string;
-            inputTokens: number;
-            outputTokens: number;
-            totalTokens: number;
-            cacheReadTokens: number;
-            cacheWriteTokens: number;
-            reasoningTokens: number;
-        }[];
-        summary: {
-            model: string;
-            inputTokens: number;
-            outputTokens: number;
-            totalTokens: number;
-            cacheReadTokens: number;
-            cacheWriteTokens: number;
-            reasoningTokens: number;
-            stepCount: number;
-        };
-    } | null;
+    usage: MessageUsage | null;
     workflowRunId?: string | null;
+    metadata?: Record<string, unknown> | null;
 };
 type Part = {
     id: string;
@@ -198,4 +253,4 @@ interface Storage {
 type StorageInput = StorageHandlers | StorageStepFunction;
 declare function toStorage(h: StorageInput): Storage;
 
-export { type Message as M, type Part as P, type StorageHandlers as S, type Sandbox as a, type Session as b, type Setup as c, type SetupSnapshot as d, type Storage as e, type StorageCall as f, StorageStep as g, type StorageStepFunction as h, type StorageInput as i, toStorage as t };
+export { type GenerationOptions as G, type HostSkillEntry as H, type InlineSkillEntry as I, type Message as M, type Part as P, type StorageHandlers as S, type MessageUsage as a, type Sandbox as b, type Session as c, type Setup as d, type SetupSnapshot as e, type Storage as f, type StorageCall as g, StorageStep as h, type StorageStepFunction as i, type SkillInput as j, type StorageInput as k, type GitSkillEntry as l, type GitSkillInput as m, type HostSkillInput as n, type InlineSkillInput as o, type SandboxSkillEntry as p, type SandboxSkillInput as q, type SkillEntry as r, type SkillSourceType as s, toStorage as t };