@aexhq/sdk 0.38.0 → 0.39.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/_contracts/index.d.ts +1 -1
- package/dist/_contracts/index.js +1 -1
- package/dist/_contracts/operations.d.ts +21 -1
- package/dist/_contracts/operations.js +43 -0
- package/dist/_contracts/run-config.d.ts +35 -10
- package/dist/_contracts/run-config.js +17 -5
- package/dist/_contracts/runtime-types.d.ts +22 -0
- package/dist/_contracts/submission.d.ts +78 -12
- package/dist/_contracts/submission.js +171 -50
- package/dist/asset-upload.d.ts +1 -1
- package/dist/asset-upload.js +1 -1
- package/dist/bundle.d.ts +9 -11
- package/dist/bundle.js +5 -6
- package/dist/bundle.js.map +1 -1
- package/dist/cli.mjs +41 -0
- package/dist/cli.mjs.sha256 +1 -1
- package/dist/client.d.ts +57 -13
- package/dist/client.js +141 -76
- package/dist/client.js.map +1 -1
- package/dist/fetch-archive.js +14 -14
- package/dist/fetch-archive.js.map +1 -1
- package/dist/index.d.ts +7 -7
- package/dist/index.js +6 -6
- package/dist/index.js.map +1 -1
- package/dist/skill.d.ts +139 -0
- package/dist/skill.js +289 -0
- package/dist/skill.js.map +1 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/concepts/composition.md +3 -3
- package/docs/mcp.md +3 -2
- package/docs/provider-runtime-capabilities.md +1 -1
- package/docs/run-config.md +1 -1
- package/docs/skills.md +74 -44
- package/docs/vision-skills.md +3 -3
- package/package.json +1 -1
- package/dist/skill-tool.d.ts +0 -102
- package/dist/skill-tool.js +0 -190
- package/dist/skill-tool.js.map +0 -1
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"skill.js","sourceRoot":"","sources":["../src/skill.ts"],"names":[],"mappings":"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"}
|
package/dist/version.d.ts
CHANGED
package/dist/version.js
CHANGED
|
@@ -10,7 +10,7 @@ runtime before the first agent turn.
|
|
|
10
10
|
|
|
11
11
|
| Need | Primitive |
|
|
12
12
|
| --- | --- |
|
|
13
|
-
|
|
|
13
|
+
| Instructional skill bundles | `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles` |
|
|
14
14
|
| Agent instructions | `AgentsMd.fromPath`, `AgentsMd.fromContent` |
|
|
15
15
|
| Reference files and folders | `File.fromPath`, `File.fromBytes` |
|
|
16
16
|
| Remote tools | `McpServer.remote`, `McpServer.fromId` |
|
|
@@ -18,14 +18,14 @@ runtime before the first agent turn.
|
|
|
18
18
|
| Runtime secrets for your code | `Secret.value`, `Secret.ref`, `environment.secrets` |
|
|
19
19
|
|
|
20
20
|
```ts
|
|
21
|
-
import { AgentsMd, File, McpServer, Models, Secret,
|
|
21
|
+
import { AgentsMd, File, McpServer, Models, Secret, Skill } from "@aexhq/sdk";
|
|
22
22
|
|
|
23
23
|
await aex.run({
|
|
24
24
|
model: Models.CLAUDE_HAIKU_4_5,
|
|
25
25
|
message: "Use the attached docs and tools to produce a report.",
|
|
26
26
|
agentsMd: [await AgentsMd.fromContent("Follow the repo conventions.", { name: "repo-rules" })],
|
|
27
27
|
files: [await File.fromPath("./input")],
|
|
28
|
-
|
|
28
|
+
skills: [await Skill.fromDir("./skills/report-writer", { name: "report-writer" })],
|
|
29
29
|
mcpServers: [McpServer.remote({ name: "github", url: "https://example.com/mcp" })],
|
|
30
30
|
environment: {
|
|
31
31
|
secrets: { INTERNAL_API_TOKEN: Secret.value(process.env.INTERNAL_API_TOKEN!) },
|
package/docs/mcp.md
CHANGED
|
@@ -29,8 +29,9 @@ For ingestion-style MCP servers that return large JSON blobs (search results,
|
|
|
29
29
|
catalogue dumps, bulk reads), prefer a skill that writes files instead of
|
|
30
30
|
putting the whole response in model context:
|
|
31
31
|
|
|
32
|
-
1. Package the upstream as a
|
|
33
|
-
|
|
32
|
+
1. Package the upstream helper as a Skill (`Skill.fromDir` / `Skill.fromUrl`)
|
|
33
|
+
and pass it via the top-level `skills` option. The skill can include a CLI
|
|
34
|
+
binary or script that the agent invokes with its bash tool.
|
|
34
35
|
2. Keep any upstream HTTPS credentials in `environment.secrets`.
|
|
35
36
|
3. Have the CLI write the full payload to the session filesystem. By default,
|
|
36
37
|
files it creates or modifies are captured automatically; pass
|
|
@@ -40,7 +40,7 @@ All new submissions run on the managed runtime. Public support is expressed as s
|
|
|
40
40
|
|
|
41
41
|
## Skills
|
|
42
42
|
|
|
43
|
-
Skills are supplied
|
|
43
|
+
Skills are supplied through the top-level `skills` option. Build one with `Skill.fromDir`, `Skill.fromUrl`, `Skill.fromFiles`, `Skill.fromContent`, or `Skill.fromBytes`; each normalizes to a named workspace skill that the platform snapshots into durable run asset storage.
|
|
44
44
|
|
|
45
45
|
Notes:
|
|
46
46
|
|
package/docs/run-config.md
CHANGED
|
@@ -16,7 +16,7 @@ Allowed fields:
|
|
|
16
16
|
- `metadata` - non-secret structured metadata.
|
|
17
17
|
- `overrides` - `{ idleTtl?, timeout?, maxSpendUsd? }`. `timeout` is an optional session deadline (e.g. `"30m"`, `"2h"`); `maxSpendUsd` stops the session once its spend would exceed the cap (see [Limits & quotas](limits-and-quotas.md)).
|
|
18
18
|
|
|
19
|
-
`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `
|
|
19
|
+
`message` (the one-shot `run` input), `agentsMd`, `files`, `outputs`, `tools`, `skills`, `includeBuiltinTools`, and `outputMode` are `openSession` / `run` options, not reusable run-config fields. They carry the turn input, bytes, capture behavior, or agent tool/output controls that belong on a concrete call. Skill bundles are `skills` entries built with `Skill.fromDir(...)`, `Skill.fromUrl(...)`, or the other `Skill.from*` factories, so they too are SDK-code options rather than config fields. Subagents are session-internal (the in-run `subagent` tool — see [Subagents](concepts/subagents.md)); there is no `parentRunId` option. The wire contract carries a per-run `limits` object (the exported `RunLimits` type: `maxConcurrentChildRuns`, `maxSubagentDepth`, `maxSpendUsd`), but the session surface exposes only its spend dial — set it with `overrides.maxSpendUsd`; the subagent depth/breadth dials are not settable per-session today and take the platform defaults.
|
|
20
20
|
|
|
21
21
|
Secrets never live in run config. Pass provider keys through the top-level
|
|
22
22
|
`apiKeys` map and runtime secrets through `environment.secrets` in the SDK, or
|
package/docs/skills.md
CHANGED
|
@@ -5,76 +5,106 @@ title: Skills
|
|
|
5
5
|
# Skills
|
|
6
6
|
|
|
7
7
|
A skill is a bundle of instructional or executable content (`SKILL.md` plus any
|
|
8
|
-
supporting files) that the agent can pull into context on demand.
|
|
9
|
-
|
|
10
|
-
`
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Build a skill
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- **Local directory:** `
|
|
19
|
-
|
|
20
|
-
|
|
8
|
+
supporting files) that the agent can pull into context on demand. Skills are a
|
|
9
|
+
**first-class concept, separate from tools**: you pass them on the session's own
|
|
10
|
+
`skills` input (not `tools`), and the run gets a single `skills` meta-tool the
|
|
11
|
+
model uses to list and load them.
|
|
12
|
+
|
|
13
|
+
Build a skill with the `Skill.from*` factories. Each reads a bundle, lifts the
|
|
14
|
+
`name` and `description` from the `SKILL.md` YAML frontmatter (an explicit
|
|
15
|
+
`{ name }` overrides the frontmatter), canonically zips + hashes the bytes, and
|
|
16
|
+
returns a `Skill`:
|
|
17
|
+
|
|
18
|
+
- **Local directory:** `Skill.fromDir(rootDir, { name? })` reads a folder with
|
|
19
|
+
`SKILL.md` at its root. With no `{ name }` and no frontmatter `name:`, the
|
|
20
|
+
slugified directory basename is used (Bun/Node filesystem runtimes).
|
|
21
|
+
- **Signed URL:** `Skill.fromUrl(url, { name?, sha256?, timeoutMs?, fetch? })`
|
|
21
22
|
fetches a zip archive with `SKILL.md` at the archive root (universal — needs a
|
|
22
23
|
global `fetch`, or pass one).
|
|
24
|
+
- **In-memory:** `Skill.fromFiles({ name?, files })` from a path→bytes map,
|
|
25
|
+
`Skill.fromContent(skillMd, { name? })` from a single `SKILL.md` string, or
|
|
26
|
+
`Skill.fromBytes({ name?, zip })` from a pre-zipped bundle.
|
|
27
|
+
|
|
28
|
+
Names must match the skill-name pattern (`^[a-z0-9][a-z0-9_-]{0,127}$`), must not
|
|
29
|
+
contain `__` (reserved for MCP tools), and must not be the reserved names
|
|
30
|
+
`skills` / `skill`. The frontmatter `description` (max 2048 chars) is required.
|
|
23
31
|
|
|
24
32
|
```ts
|
|
25
|
-
import { Aex, Models,
|
|
33
|
+
import { Aex, Models, Skill } from "@aexhq/sdk";
|
|
26
34
|
|
|
27
35
|
const aex = new Aex({ apiKey });
|
|
28
36
|
|
|
29
37
|
await aex.run({
|
|
30
38
|
model: Models.CLAUDE_HAIKU_4_5,
|
|
31
39
|
message,
|
|
32
|
-
|
|
40
|
+
skills: [await Skill.fromDir("./skills/rules", { name: "rules" })],
|
|
33
41
|
apiKeys: { anthropic: apiKey }
|
|
34
42
|
});
|
|
35
43
|
```
|
|
36
44
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
45
|
+
## By-name, mutable binding
|
|
46
|
+
|
|
47
|
+
A skill is bound to the workspace **by name**. `skill.upload(client)` UPSERTS the
|
|
48
|
+
workspace skill under its name; a re-upload under the same name changes what
|
|
49
|
+
every future run referencing that name sees. The wire ref is name-only —
|
|
50
|
+
`{ kind:"skill", name }` — with no `assetId` and no hash, so the idempotency hash
|
|
51
|
+
of two runs that reference the same skill name is identical even if the skill's
|
|
52
|
+
bytes changed between them.
|
|
53
|
+
|
|
54
|
+
Passing a **draft** `Skill` in `skills:` auto-upserts it on submit (the same
|
|
55
|
+
ergonomic as a draft `Tool` / `File`). To upsert explicitly and reuse the name
|
|
56
|
+
across many runs:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
const rules = await Skill.fromDir("./skills/rules", { name: "rules" });
|
|
60
|
+
await rules.upload(aex); // stage bytes + PUT /skills/rules
|
|
61
|
+
await aex.run({ model, message, skills: [rules], apiKeys });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`upload()` is idempotent on an instance (it caches the resolved name, so reuse
|
|
65
|
+
across submits skips the round-trip) and identical bytes are a server no-op.
|
|
42
66
|
|
|
43
|
-
|
|
67
|
+
### How a skill rides on the wire
|
|
44
68
|
|
|
45
|
-
Before the session lands, `openSession` / `run` walks the `
|
|
46
|
-
|
|
69
|
+
Before the session lands, `openSession` / `run` walks the `skills` array and, for
|
|
70
|
+
each draft, upserts it by name:
|
|
47
71
|
|
|
48
72
|
1. `POST /assets/presign` checks for a dedup hit and, when needed, returns a
|
|
49
73
|
signed upload URL.
|
|
50
74
|
2. The SDK PUTs bytes directly to object storage with the signed checksum headers.
|
|
51
75
|
3. `POST /assets/finalize` confirms the object exists.
|
|
76
|
+
4. `PUT /skills/{name}` binds that content hash to the mutable workspace skill
|
|
77
|
+
name (identical `contentHash` ⇒ no-op).
|
|
78
|
+
|
|
79
|
+
The submission then carries only `submission.skills: [{ kind:"skill", name }]`.
|
|
80
|
+
The four prepare passes (tools, skills, agentsMd, files) upload with bounded
|
|
81
|
+
concurrency and run concurrently with each other.
|
|
82
|
+
|
|
83
|
+
## The `skills` meta-tool
|
|
52
84
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
the same bundle is a no-op upload; a `SkillTool` instance also caches its resolved
|
|
56
|
-
asset id, so reusing the same instance across sessions skips the re-upload. A URL
|
|
57
|
-
is an ingestion source, not a persistent reference — the SDK snapshots the fetched
|
|
58
|
-
bytes into the asset store, and the hosted platform never fetches the
|
|
59
|
-
caller-controlled URL.
|
|
85
|
+
When a run references at least one skill, the platform injects a single `skills`
|
|
86
|
+
meta-tool:
|
|
60
87
|
|
|
61
|
-
|
|
88
|
+
- `skills({ action: "list" })` returns each skill's `name` + `description`
|
|
89
|
+
(cheap — do this first).
|
|
90
|
+
- `skills({ action: "load", name: "<skill>"})` reads that skill's full `SKILL.md`
|
|
91
|
+
instructions into context.
|
|
62
92
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
93
|
+
A skill's supporting files are staged to disk under `/workspace/skills/<name>/`
|
|
94
|
+
from the first turn, so `load` pulls the instructions while `read_file` / `bash`
|
|
95
|
+
read the rest. The run resolves each referenced name to the workspace skill's
|
|
96
|
+
current bytes at submit time and snapshots them into durable run asset storage
|
|
97
|
+
(`runs/<runId>/assets/<hash>`); run-scoped copies are removed by run deletion or
|
|
98
|
+
retention cleanup.
|
|
67
99
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
100
|
+
## Workspace skill admin
|
|
101
|
+
|
|
102
|
+
`client.skills` is the metadata surface for the named registry:
|
|
103
|
+
|
|
104
|
+
- `client.skills.list()` — skill metadata (never bytes).
|
|
105
|
+
- `client.skills.get(name)` — one skill's metadata.
|
|
106
|
+
- `client.skills.delete(name)` — remove a workspace skill.
|
|
74
107
|
|
|
75
108
|
Skills that call external HTTP APIs should read credentials from
|
|
76
109
|
`environment.secrets` and use the normal client for that service. See
|
|
77
110
|
[Credentials](credentials.md) for the secret model.
|
|
78
|
-
|
|
79
|
-
Run-scoped asset copies are part of the run record and are removed by run deletion
|
|
80
|
-
or retention cleanup.
|
package/docs/vision-skills.md
CHANGED
|
@@ -16,14 +16,14 @@ per-noun "does the frame depict X?" verdict.
|
|
|
16
16
|
## Submit the run
|
|
17
17
|
|
|
18
18
|
```ts
|
|
19
|
-
import { Aex, Models, Secret,
|
|
19
|
+
import { Aex, Models, Secret, Skill } from "@aexhq/sdk";
|
|
20
20
|
|
|
21
21
|
const aex = new Aex({ apiKey: process.env.AEX_API_KEY! });
|
|
22
22
|
|
|
23
23
|
const result = await aex.run({
|
|
24
24
|
model: Models.CLAUDE_HAIKU_4_5,
|
|
25
25
|
message: "Read skills/frame-vision-gate/SKILL.md, then caption and verify the frame.",
|
|
26
|
-
|
|
26
|
+
skills: [await Skill.fromDir("./vision-skill", { name: "frame-vision-gate" })],
|
|
27
27
|
environment: {
|
|
28
28
|
secrets: {
|
|
29
29
|
DOUBAO_API_KEY: Secret.value(process.env.DOUBAO_API_KEY!)
|
|
@@ -39,7 +39,7 @@ const result = await aex.run({
|
|
|
39
39
|
console.log(result.runId, result.text);
|
|
40
40
|
```
|
|
41
41
|
|
|
42
|
-
`
|
|
42
|
+
`Skill.fromDir("./vision-skill", ...)` is resolved relative to the process
|
|
43
43
|
CWD. Run the script from the directory that contains `vision-skill/` (in this
|
|
44
44
|
repo, `examples/`).
|
|
45
45
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aexhq/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.39.0",
|
|
4
4
|
"description": "TypeScript SDK for running autonomous agent sessions across providers (Anthropic, OpenAI, DeepSeek, Gemini, Mistral) behind one interface.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
package/dist/skill-tool.d.ts
DELETED
|
@@ -1,102 +0,0 @@
|
|
|
1
|
-
import { type FetchLike, type SkillToolRef } from "./_contracts/index.js";
|
|
2
|
-
import { type SkillFiles } from "./bundle.js";
|
|
3
|
-
/**
|
|
4
|
-
* A skill re-expressed as a TOOL. `Tools.fromSkillDir` / `Tools.fromSkillUrl`
|
|
5
|
-
* read a skill folder/zip, lift the tool `name` + `description` from the
|
|
6
|
-
* `SKILL.md` YAML frontmatter, and canonically bundle+hash the bytes. The
|
|
7
|
-
* result rides in the session's `tools` array (next to builtin names and custom
|
|
8
|
-
* {@link Tool} bundles); `client.run` / `openSession` uploads the bundle as an
|
|
9
|
-
* asset before the run lands, and the wire ref becomes a
|
|
10
|
-
* `{ kind:"skill", assetId, name, description }` {@link SkillToolRef}.
|
|
11
|
-
*
|
|
12
|
-
* At run time the model calls the no-arg load-tool to pull the skill's
|
|
13
|
-
* `SKILL.md` body into context; the bundle's files are eagerly staged to
|
|
14
|
-
* `/workspace/skills/<name>/`.
|
|
15
|
-
*
|
|
16
|
-
* Asset deduplication makes the same bytes a no-op upload on subsequent runs.
|
|
17
|
-
* A URL is an ingestion source, not a persistent reference.
|
|
18
|
-
*/
|
|
19
|
-
export declare class SkillTool {
|
|
20
|
-
#private;
|
|
21
|
-
/** Internal constructor. Use the `Tools.fromSkill*` factories. */
|
|
22
|
-
private constructor();
|
|
23
|
-
/**
|
|
24
|
-
* The wire-level reference. Returns the SDK-private draft shape for
|
|
25
|
-
* un-uploaded skill-tools (kind:"draft", with name + description +
|
|
26
|
-
* contentHash). `client.run` / `openSession` walks these and uploads them
|
|
27
|
-
* before the run lands.
|
|
28
|
-
*/
|
|
29
|
-
get ref(): SkillToolRef | DraftSkillToolRef;
|
|
30
|
-
/** True for local-bytes skill-tools that haven't been uploaded yet. */
|
|
31
|
-
get isDraft(): boolean;
|
|
32
|
-
/** Internal: the asset id resolved on a prior use, or undefined. */
|
|
33
|
-
get _cachedAssetId(): string | undefined;
|
|
34
|
-
/** Internal: remember the asset id resolved for this draft's bytes. */
|
|
35
|
-
_rememberAsset(assetId: string): void;
|
|
36
|
-
/** Internal: build a draft from an already-loaded skill files map. */
|
|
37
|
-
static _fromFiles(source: string, files: SkillFiles, nameOverride: string | undefined): Promise<SkillTool>;
|
|
38
|
-
/**
|
|
39
|
-
* Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
|
|
40
|
-
* can upload the asset. Idempotent (non-consuming): a SkillTool is reusable
|
|
41
|
-
* across sessions — the first use caches the resolved asset id (see
|
|
42
|
-
* `_rememberAsset`) so later uses reuse it instead of re-uploading.
|
|
43
|
-
*
|
|
44
|
-
* Returns undefined for already-uploaded skill-tools.
|
|
45
|
-
*/
|
|
46
|
-
_takeDraftBundle(): {
|
|
47
|
-
name: string;
|
|
48
|
-
description: string;
|
|
49
|
-
contentHash: string;
|
|
50
|
-
bytes: Uint8Array;
|
|
51
|
-
} | undefined;
|
|
52
|
-
toJSON(): SkillToolRef;
|
|
53
|
-
}
|
|
54
|
-
/**
|
|
55
|
-
* SDK-internal draft skill-tool marker. Never reaches the wire; the
|
|
56
|
-
* materialize step inside `client.run` / `openSession` converts these to
|
|
57
|
-
* `kind:"skill"` refs once the bundle is uploaded.
|
|
58
|
-
*/
|
|
59
|
-
export interface DraftSkillToolRef {
|
|
60
|
-
readonly kind: "draft";
|
|
61
|
-
readonly name: string;
|
|
62
|
-
readonly description: string;
|
|
63
|
-
readonly contentHash: string;
|
|
64
|
-
}
|
|
65
|
-
/**
|
|
66
|
-
* Factory namespace for skill-tools. Each factory reads a skill bundle, lifts
|
|
67
|
-
* `name` + `description` from the `SKILL.md` frontmatter (an explicit `name`
|
|
68
|
-
* argument overrides the frontmatter), and produces a {@link SkillTool} to pass
|
|
69
|
-
* in the session's `tools` array.
|
|
70
|
-
*/
|
|
71
|
-
export declare const Tools: {
|
|
72
|
-
/**
|
|
73
|
-
* Read a local skill directory and build a skill-tool. The directory must
|
|
74
|
-
* contain `SKILL.md` at its root, whose YAML frontmatter provides the tool
|
|
75
|
-
* `name` (unless overridden via `args.name`) and `description`. Symlinks and
|
|
76
|
-
* non-regular files are skipped. Bun/Node filesystem runtimes only.
|
|
77
|
-
*/
|
|
78
|
-
readonly fromSkillDir: (rootDir: string, args?: {
|
|
79
|
-
readonly name?: string;
|
|
80
|
-
}) => Promise<SkillTool>;
|
|
81
|
-
/**
|
|
82
|
-
* Fetch a zip-archived skill from a URL and build a skill-tool. The archive is
|
|
83
|
-
* downloaded in the SDK process, so the URL is caller-controlled — host the
|
|
84
|
-
* skill yourself and pass a temporary signed URL (e.g. an S3 presigned URL).
|
|
85
|
-
* Its bytes are optionally integrity-checked against `sha256`, unzipped, and
|
|
86
|
-
* reduced to the same files map as `Tools.fromSkillDir`, so a URL-sourced
|
|
87
|
-
* skill and the identical local skill produce the same canonical asset and
|
|
88
|
-
* dedup against each other.
|
|
89
|
-
*
|
|
90
|
-
* The archive must contain `SKILL.md` at its root, or inside a single
|
|
91
|
-
* top-level folder (which is stripped). The signed URL only needs to be valid
|
|
92
|
-
* for this call; `client.run` / `openSession` snapshots the bytes into the run.
|
|
93
|
-
*
|
|
94
|
-
* Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
|
|
95
|
-
*/
|
|
96
|
-
readonly fromSkillUrl: (url: string, args?: {
|
|
97
|
-
readonly name?: string;
|
|
98
|
-
readonly sha256?: string;
|
|
99
|
-
readonly timeoutMs?: number;
|
|
100
|
-
readonly fetch?: FetchLike;
|
|
101
|
-
}) => Promise<SkillTool>;
|
|
102
|
-
};
|
package/dist/skill-tool.js
DELETED
|
@@ -1,190 +0,0 @@
|
|
|
1
|
-
import { TOOL_NAME_PATTERN } from "./_contracts/index.js";
|
|
2
|
-
import { bundleSkillFiles, hashSkillBundle } from "./bundle.js";
|
|
3
|
-
import { fetchSkillArchive } from "./fetch-archive.js";
|
|
4
|
-
import { readDirectoryAsFiles } from "./node-fs.js";
|
|
5
|
-
/**
|
|
6
|
-
* A skill re-expressed as a TOOL. `Tools.fromSkillDir` / `Tools.fromSkillUrl`
|
|
7
|
-
* read a skill folder/zip, lift the tool `name` + `description` from the
|
|
8
|
-
* `SKILL.md` YAML frontmatter, and canonically bundle+hash the bytes. The
|
|
9
|
-
* result rides in the session's `tools` array (next to builtin names and custom
|
|
10
|
-
* {@link Tool} bundles); `client.run` / `openSession` uploads the bundle as an
|
|
11
|
-
* asset before the run lands, and the wire ref becomes a
|
|
12
|
-
* `{ kind:"skill", assetId, name, description }` {@link SkillToolRef}.
|
|
13
|
-
*
|
|
14
|
-
* At run time the model calls the no-arg load-tool to pull the skill's
|
|
15
|
-
* `SKILL.md` body into context; the bundle's files are eagerly staged to
|
|
16
|
-
* `/workspace/skills/<name>/`.
|
|
17
|
-
*
|
|
18
|
-
* Asset deduplication makes the same bytes a no-op upload on subsequent runs.
|
|
19
|
-
* A URL is an ingestion source, not a persistent reference.
|
|
20
|
-
*/
|
|
21
|
-
export class SkillTool {
|
|
22
|
-
#ref;
|
|
23
|
-
#inlineBytes;
|
|
24
|
-
/** Asset id cached after the first use, so reuse skips a re-upload. */
|
|
25
|
-
#assetId;
|
|
26
|
-
/** Internal constructor. Use the `Tools.fromSkill*` factories. */
|
|
27
|
-
constructor(ref, inlineBytes) {
|
|
28
|
-
this.#ref = ref;
|
|
29
|
-
this.#inlineBytes = inlineBytes;
|
|
30
|
-
}
|
|
31
|
-
/**
|
|
32
|
-
* The wire-level reference. Returns the SDK-private draft shape for
|
|
33
|
-
* un-uploaded skill-tools (kind:"draft", with name + description +
|
|
34
|
-
* contentHash). `client.run` / `openSession` walks these and uploads them
|
|
35
|
-
* before the run lands.
|
|
36
|
-
*/
|
|
37
|
-
get ref() {
|
|
38
|
-
return this.#ref;
|
|
39
|
-
}
|
|
40
|
-
/** True for local-bytes skill-tools that haven't been uploaded yet. */
|
|
41
|
-
get isDraft() {
|
|
42
|
-
return this.#ref.kind === "draft";
|
|
43
|
-
}
|
|
44
|
-
/** Internal: the asset id resolved on a prior use, or undefined. */
|
|
45
|
-
get _cachedAssetId() {
|
|
46
|
-
return this.#assetId;
|
|
47
|
-
}
|
|
48
|
-
/** Internal: remember the asset id resolved for this draft's bytes. */
|
|
49
|
-
_rememberAsset(assetId) {
|
|
50
|
-
this.#assetId = assetId;
|
|
51
|
-
}
|
|
52
|
-
/** Internal: build a draft from an already-loaded skill files map. */
|
|
53
|
-
static async _fromFiles(source, files, nameOverride) {
|
|
54
|
-
const front = extractSkillFrontmatter(source, files);
|
|
55
|
-
const name = nameOverride ?? front.name;
|
|
56
|
-
if (typeof name !== "string" || name.length === 0) {
|
|
57
|
-
throw new Error(`${source}: a skill name is required — pass { name } or add a \`name:\` field to the SKILL.md YAML frontmatter`);
|
|
58
|
-
}
|
|
59
|
-
if (!TOOL_NAME_PATTERN.test(name)) {
|
|
60
|
-
throw new Error(`${source}: name must match ${TOOL_NAME_PATTERN.source}`);
|
|
61
|
-
}
|
|
62
|
-
if (name.includes("__")) {
|
|
63
|
-
throw new Error(`${source}: name must not contain "__"; that separator is reserved for MCP tools`);
|
|
64
|
-
}
|
|
65
|
-
const description = front.description;
|
|
66
|
-
if (typeof description !== "string" || description.trim().length === 0) {
|
|
67
|
-
throw new Error(`${source}: a skill description is required — add a \`description:\` field to the SKILL.md YAML frontmatter`);
|
|
68
|
-
}
|
|
69
|
-
if (description.length > 2048) {
|
|
70
|
-
throw new Error(`${source}: description must be <= 2048 chars`);
|
|
71
|
-
}
|
|
72
|
-
const bundled = bundleSkillFiles(files);
|
|
73
|
-
const contentHash = await hashSkillBundle(bundled.zip);
|
|
74
|
-
const ref = { kind: "draft", name, description, contentHash };
|
|
75
|
-
return new SkillTool(ref, bundled.zip);
|
|
76
|
-
}
|
|
77
|
-
/**
|
|
78
|
-
* Internal: yield the draft's bytes + metadata so `client.run` / `openSession`
|
|
79
|
-
* can upload the asset. Idempotent (non-consuming): a SkillTool is reusable
|
|
80
|
-
* across sessions — the first use caches the resolved asset id (see
|
|
81
|
-
* `_rememberAsset`) so later uses reuse it instead of re-uploading.
|
|
82
|
-
*
|
|
83
|
-
* Returns undefined for already-uploaded skill-tools.
|
|
84
|
-
*/
|
|
85
|
-
_takeDraftBundle() {
|
|
86
|
-
if (this.#ref.kind !== "draft" || !this.#inlineBytes) {
|
|
87
|
-
return undefined;
|
|
88
|
-
}
|
|
89
|
-
return {
|
|
90
|
-
name: this.#ref.name,
|
|
91
|
-
description: this.#ref.description,
|
|
92
|
-
contentHash: this.#ref.contentHash,
|
|
93
|
-
bytes: this.#inlineBytes
|
|
94
|
-
};
|
|
95
|
-
}
|
|
96
|
-
toJSON() {
|
|
97
|
-
if (this.#ref.kind === "draft") {
|
|
98
|
-
throw new Error("SkillTool: draft skill-tools cannot be JSON-serialised — they only become wire refs when " +
|
|
99
|
-
"aex.run / openSession uploads the bytes as an asset.");
|
|
100
|
-
}
|
|
101
|
-
return this.#ref;
|
|
102
|
-
}
|
|
103
|
-
}
|
|
104
|
-
/**
|
|
105
|
-
* Factory namespace for skill-tools. Each factory reads a skill bundle, lifts
|
|
106
|
-
* `name` + `description` from the `SKILL.md` frontmatter (an explicit `name`
|
|
107
|
-
* argument overrides the frontmatter), and produces a {@link SkillTool} to pass
|
|
108
|
-
* in the session's `tools` array.
|
|
109
|
-
*/
|
|
110
|
-
export const Tools = {
|
|
111
|
-
/**
|
|
112
|
-
* Read a local skill directory and build a skill-tool. The directory must
|
|
113
|
-
* contain `SKILL.md` at its root, whose YAML frontmatter provides the tool
|
|
114
|
-
* `name` (unless overridden via `args.name`) and `description`. Symlinks and
|
|
115
|
-
* non-regular files are skipped. Bun/Node filesystem runtimes only.
|
|
116
|
-
*/
|
|
117
|
-
async fromSkillDir(rootDir, args = {}) {
|
|
118
|
-
const files = await readDirectoryAsFiles(rootDir);
|
|
119
|
-
return SkillTool._fromFiles("Tools.fromSkillDir", files, args.name);
|
|
120
|
-
},
|
|
121
|
-
/**
|
|
122
|
-
* Fetch a zip-archived skill from a URL and build a skill-tool. The archive is
|
|
123
|
-
* downloaded in the SDK process, so the URL is caller-controlled — host the
|
|
124
|
-
* skill yourself and pass a temporary signed URL (e.g. an S3 presigned URL).
|
|
125
|
-
* Its bytes are optionally integrity-checked against `sha256`, unzipped, and
|
|
126
|
-
* reduced to the same files map as `Tools.fromSkillDir`, so a URL-sourced
|
|
127
|
-
* skill and the identical local skill produce the same canonical asset and
|
|
128
|
-
* dedup against each other.
|
|
129
|
-
*
|
|
130
|
-
* The archive must contain `SKILL.md` at its root, or inside a single
|
|
131
|
-
* top-level folder (which is stripped). The signed URL only needs to be valid
|
|
132
|
-
* for this call; `client.run` / `openSession` snapshots the bytes into the run.
|
|
133
|
-
*
|
|
134
|
-
* Universal (Bun / Node 18+ / browser): requires a global `fetch`, or pass one.
|
|
135
|
-
*/
|
|
136
|
-
async fromSkillUrl(url, args = {}) {
|
|
137
|
-
const files = await fetchSkillArchive(url, {
|
|
138
|
-
...(args.sha256 !== undefined ? { sha256: args.sha256 } : {}),
|
|
139
|
-
...(args.timeoutMs !== undefined ? { timeoutMs: args.timeoutMs } : {}),
|
|
140
|
-
...(args.fetch !== undefined ? { fetch: args.fetch } : {})
|
|
141
|
-
});
|
|
142
|
-
return SkillTool._fromFiles("Tools.fromSkillUrl", files, args.name);
|
|
143
|
-
}
|
|
144
|
-
};
|
|
145
|
-
/**
|
|
146
|
-
* Read `SKILL.md` from a bundle files map and parse its YAML frontmatter for
|
|
147
|
-
* the `name` + `description` fields. Throws when the bundle has no root
|
|
148
|
-
* `SKILL.md` (that is what makes a bundle a skill).
|
|
149
|
-
*/
|
|
150
|
-
function extractSkillFrontmatter(source, files) {
|
|
151
|
-
const raw = files["SKILL.md"];
|
|
152
|
-
if (raw === undefined) {
|
|
153
|
-
throw new Error(`${source}: the skill bundle must contain a SKILL.md at its root`);
|
|
154
|
-
}
|
|
155
|
-
const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
|
|
156
|
-
return parseSkillFrontmatter(text);
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* Minimal YAML-frontmatter reader: pulls the `name` and `description` scalar
|
|
160
|
-
* values out of the leading `--- … ---` block. Only simple single-line
|
|
161
|
-
* `key: value` entries are supported (surrounding single/double quotes are
|
|
162
|
-
* stripped); anything else is ignored. A skill with no frontmatter yields an
|
|
163
|
-
* empty result and the caller reports the missing field.
|
|
164
|
-
*/
|
|
165
|
-
function parseSkillFrontmatter(text) {
|
|
166
|
-
const src = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
|
|
167
|
-
const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(src);
|
|
168
|
-
if (!match) {
|
|
169
|
-
return {};
|
|
170
|
-
}
|
|
171
|
-
const out = {};
|
|
172
|
-
for (const line of match[1].split(/\r?\n/)) {
|
|
173
|
-
const kv = /^([A-Za-z0-9_-]+)[ \t]*:[ \t]*(.*)$/.exec(line);
|
|
174
|
-
if (!kv)
|
|
175
|
-
continue;
|
|
176
|
-
const key = kv[1].toLowerCase();
|
|
177
|
-
if (key !== "name" && key !== "description")
|
|
178
|
-
continue;
|
|
179
|
-
let value = kv[2].trim();
|
|
180
|
-
if (value.length >= 2 &&
|
|
181
|
-
((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
|
|
182
|
-
value = value.slice(1, -1);
|
|
183
|
-
}
|
|
184
|
-
if (value.length > 0) {
|
|
185
|
-
out[key] = value;
|
|
186
|
-
}
|
|
187
|
-
}
|
|
188
|
-
return out;
|
|
189
|
-
}
|
|
190
|
-
//# sourceMappingURL=skill-tool.js.map
|
package/dist/skill-tool.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"skill-tool.js","sourceRoot":"","sources":["../src/skill-tool.ts"],"names":[],"mappings":"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"}
|