@operatorstack/yield 0.1.30 → 0.1.32

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 CHANGED
@@ -1,206 +1,272 @@
1
- # Yield
1
+ <p align="center">
2
+ <a href="https://yield.operatorstack.systems/">
3
+ <img src="https://raw.githubusercontent.com/operatorstack/yield/main/assets/yield-mark.svg" width="96" height="96" alt="Yield" />
4
+ </a>
5
+ </p>
6
+
7
+ <h1 align="center">Yield</h1>
8
+
9
+ <p align="center"><strong>Move repeatable coding-agent instructions from words into code.</strong></p>
10
+
11
+ <p align="center">
12
+ In-repository workflows for TypeScript, Python, Go, and Rust.
13
+ </p>
14
+
15
+ <p align="center">
16
+ <a href="https://www.npmjs.com/package/@operatorstack/yield"><img alt="npm version" src="https://img.shields.io/npm/v/@operatorstack/yield?style=flat-square" /></a>
17
+ <a href="https://github.com/operatorstack/yield/actions/workflows/verify.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/operatorstack/yield/verify.yml?branch=main&amp;style=flat-square&amp;label=build" /></a>
18
+ <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/@operatorstack/yield?style=flat-square" /></a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="https://yield.operatorstack.systems/">Website</a> ·
23
+ <a href="https://yield.operatorstack.systems/docs/">Documentation</a> ·
24
+ <a href="https://www.npmjs.com/package/@operatorstack/yield">npm</a> ·
25
+ <a href="https://github.com/operatorstack/yield">GitHub</a>
26
+ </p>
27
+
28
+ Yield turns repeated instructions for coding agents into typed, resumable
29
+ programs. The canonical workflow stays inside your repository beside the code
30
+ and dependencies it uses. Generated `SKILL.md` files only help coding agents
31
+ discover it.
32
+
33
+ Verified with Cursor, Codex, and Claude Code. Registry-backed project paths are
34
+ available for 73 more coding agents.
35
+
36
+ ## Move repeated instructions into code
37
+
38
+ A release skill often starts as prose:
39
+
40
+ > Run the tests. Review the release. Stop if the review finds a critical issue.
41
+ > Ask me before publishing. Publish the package, then verify the registry.
42
+
43
+ Yield makes the order and stopping rules executable:
44
+
45
+ <!-- release-example:start -->
46
+ ```typescript
47
+ import { defineSkill } from "@operatorstack/yield";
48
+
49
+ type Review = { critical: number; summary: string };
50
+
51
+ defineSkill((ctx) => {
52
+ // Yield runs commands itself and records their output and exit status.
53
+ const tests = ctx.runCommand("test", "echo tests-ok", 300);
54
+
55
+ // A failed requirement stops the workflow and keeps its evidence.
56
+ ctx.require(tests.exit_code === 0, "the test command succeeds", tests);
57
+
58
+ // Review gives TypeScript its compile-time type. The JSON schema checks the
59
+ // coding agent's response at runtime before this workflow can continue.
60
+ const review = ctx.agentTask<Review>(
61
+ "review-release",
62
+ "Review this release. Report critical findings and a short summary.",
63
+ { stdout: tests.stdout, stderr: tests.stderr },
64
+ {
65
+ type: "object",
66
+ required: ["critical", "summary"],
67
+ properties: {
68
+ critical: { type: "integer", minimum: 0 },
69
+ summary: { type: "string", minLength: 1 },
70
+ },
71
+ },
72
+ );
73
+ ctx.require(review.critical === 0, "the review has no critical findings", review);
74
+
75
+ // Yield emits these fixed choices. A supported host may show native controls;
76
+ // otherwise the coding agent asks through its normal interface.
77
+ const approval = ctx.askUser("approve-publish", "Publish this package?", [
78
+ { value: "yes", label: "Publish" },
79
+ { value: "no", label: "Stop" },
80
+ ]);
81
+ if (approval !== "yes") ctx.refused("the operator declined publication");
82
+
83
+ // Publishing cannot start before approval. Verification is a separate step,
84
+ // so completion requires evidence that the registry contains the release.
85
+ const publish = ctx.runCommand("publish", "echo publish-ok", 600);
86
+ ctx.require(publish.exit_code === 0, "the publish command succeeds", publish);
87
+
88
+ const registry = ctx.runCommand("verify-registry", "echo registry-ok", 300);
89
+ ctx.require(registry.exit_code === 0, "the registry contains the release", registry);
90
+
91
+ return { published: true, summary: review.summary };
92
+ });
93
+ ```
94
+ <!-- release-example:end -->
2
95
 
3
- Yield is an open-source execution runtime for programmable Agent Skill workflows.
96
+ The example uses harmless commands so its fixture can run in any checkout.
97
+ Replace them with the test, publish, and registry commands for your project.
98
+ The complete tested source is in
99
+ [`examples/release-checklist`](examples/release-checklist/).
4
100
 
5
- **Write one skill workflow. Run it from your coding agents.**
101
+ ## Use Yield in five steps
6
102
 
7
- Skill workflows are portable, executable processes that combine agent skills
8
- with deterministic code, state, and verification.
103
+ ### 1. Install Yield
9
104
 
10
- Write the workflow in TypeScript, Python, Go, or Rust. Combine agent judgment,
11
- real commands, human input, checks, and saved state. Yield generates the small
12
- adapter each coding agent expects.
105
+ Install the TypeScript SDK and its repository-local CLI in your project:
13
106
 
14
- The split is small:
107
+ ```bash
108
+ npm install --save-exact @operatorstack/yield
109
+ npm exec -- yskill --version
110
+ ```
15
111
 
16
- | term | meaning |
17
- |---|---|
18
- | **skill** | one reusable capability |
19
- | **workflow** | order, branches, checks, and saved state |
20
- | **skill workflow** | an executable composition of skills, code, commands, and human input |
21
- | **adapter** | a generated `SKILL.md` that lets one coding agent discover the workflow |
112
+ [Public npm releases](https://www.npmjs.com/package/@operatorstack/yield)
113
+ use trusted publishing. The SDK package and all six runtime packages include
114
+ SLSA v1 provenance.
22
115
 
23
- The canonical skill workflow stays beside your code. Generated adapters are
24
- disposable. The model keeps reasoning, exploration, editing, and judgment;
25
- normal code owns the repeatable control flow.
116
+ ### 2. Create the workflow
26
117
 
27
- ## Install
118
+ ```bash
119
+ npm exec -- yskill init skills/release \
120
+ --language typescript \
121
+ --description "Test, review, approve, publish, and verify a package."
122
+ ```
28
123
 
29
- Choose one language package. TypeScript and Python include a package-local
30
- runtime. Go and Rust install the matching runtime under `.yield/bin` in the
31
- repository. Generated adapters never use a global `yskill` from `PATH`.
124
+ The command creates one canonical workflow inside your repository:
125
+
126
+ ```text
127
+ skills/
128
+ └── release/
129
+ ├── SKILL.md
130
+ ├── fixtures/
131
+ │ ├── responses.json
132
+ │ └── test.json
133
+ ├── main.ts
134
+ ├── package.json
135
+ └── skill.json
136
+ ```
137
+
138
+ Replace the starter in `skills/release/main.ts` with your workflow. Update
139
+ `skills/release/fixtures/responses.json` with deterministic answers for agent
140
+ and user operations.
141
+
142
+ ### 3. Test the workflow
32
143
 
33
144
  ```bash
34
- # TypeScript (public npm)
35
- npm install --save-exact @operatorstack/yield@0.1.29
36
- npm exec -- yskill --version
145
+ npm exec -- yskill doctor skills/release --test
146
+ ```
37
147
 
38
- # Python, after creating and activating .venv
39
- python -m pip install yieldskill==0.1.29 --index-url https://get.operatorstack.systems/pip/simple/
40
- python -m yieldskill --version
148
+ This runs commands for real and supplies agent and user responses from the
149
+ fixture. A successful test reaches `completed` without leaving a run journal.
41
150
 
42
- # Go, from the repository root
43
- mkdir -p .yield/bin
44
- GOBIN="$PWD/.yield/bin" GOPROXY=https://get.operatorstack.systems/go,direct \
45
- go install github.com/operatorstack/yield/cmd/yskill@v0.1.29
46
- .yield/bin/yskill --version
151
+ ### 4. Register the skill
47
152
 
48
- # Rust, from the repository root
49
- cargo install yieldskill@0.1.29 --root .yield \
50
- --index sparse+https://get.operatorstack.systems/cargo/index/ --locked
51
- .yield/bin/yskill --version
153
+ Registration is the discovery step. This command detects installed verified
154
+ agents and writes a small adapter for each one:
155
+
156
+ ```bash
157
+ npm exec -- yskill register skills/release
52
158
  ```
53
159
 
54
- Yield creates `.yield/.gitignore` when it registers a Go or Rust workflow, so
55
- the local runtime and run state stay out of Git.
56
- On Windows, run the local binary as `.\.yield\bin\yskill.exe`.
160
+ Select verified agents explicitly when you do not want automatic detection:
57
161
 
58
- ## Create and register a skill workflow
162
+ ```bash
163
+ npm exec -- yskill register skills/release \
164
+ --agent cursor,codex,claude-code
165
+ ```
59
166
 
60
- Keep the canonical workflow beside the language dependencies it uses. Yield writes
61
- small adapters into each coding agent's project skill directory; it does not
62
- copy the workflow or install its dependencies again.
167
+ If all three are selected, Yield creates these generated files:
63
168
 
64
- ```bash
65
- # TypeScript example
66
- npm exec -- yskill init skills/review \
67
- --language typescript \
68
- --description "Review changed code when the user wants a branch checked before shipping."
169
+ ```text
170
+ .cursor/skills/release/SKILL.md # Cursor
171
+ .agents/skills/release/SKILL.md # Codex
172
+ .claude/skills/release/SKILL.md # Claude Code
173
+ ```
174
+
175
+ The adapters point back to `skills/release`. They do not copy the workflow or
176
+ install its dependencies again.
69
177
 
70
- # Replace the intentionally incomplete starter and fixture, then check it.
71
- npm exec -- yskill doctor skills/review --test
178
+ ### 5. Run the skill
72
179
 
73
- # Detect installed agents, or pass --agent cursor,codex,claude-code.
74
- npm exec -- yskill register skills/review
180
+ Start a new coding-agent session so it discovers the registered skill. Where
181
+ slash skills are supported, run:
182
+
183
+ ```text
184
+ /release
75
185
  ```
76
186
 
77
- `yskill agents` lists the available agent IDs and project paths. Cursor,
78
- Codex, and Claude Code are verified. Remaining entries support explicit path
79
- registration from the pinned open registry; they are not presented as
80
- end-to-end verified.
187
+ Otherwise, ask the agent in plain language:
188
+
189
+ ```text
190
+ Use the release skill to publish this package.
191
+ ```
81
192
 
82
- ## How a skill workflow runs
193
+ The agent follows the generated adapter, runs the canonical workflow in
194
+ `skills/release`, and asks for each required agent or user response.
83
195
 
84
- Deterministic re-execution: on every run/resume, `yskill` re-executes the
85
- skill workflow from the top, feeding recorded responses back in order. At
86
- the first unanswered operation the SDK emits a `yield.v1` request envelope
87
- and the process exits — no daemon. A replayed step that produces a
88
- different operation than the journal recorded is a divergence and fails
89
- the run loudly; it never silently forks.
196
+ ## How Yield runs and resumes
90
197
 
91
- - **`yskill`** owns the append-only run log
92
- (`.yield/runs/<id>.jsonl`), sequence and digest binding, response
93
- validation, and every refusal (stale, duplicate, wrong-run,
94
- schema-invalid, digest-mismatch, completion-unproven).
95
- - **The skill workflow** is an ordinary program using one Yield SDK; every
96
- side effect crosses a yielded primitive.
198
+ 1. Your workflow emits one typed operation.
199
+ 2. Yield records the request and exits. It does not run a daemon.
200
+ 3. The coding agent, user, or CLI supplies the result.
201
+ 4. Yield resumes from the journal and replays the program to the next operation.
97
202
 
98
- Five primitives, two exits:
203
+ If replay produces a different operation, the run fails instead of silently
204
+ forking. Every side effect crosses one of these primitives:
99
205
 
100
- | primitive | who acts |
206
+ | Primitive | Purpose |
101
207
  |---|---|
102
- | `AskUser` | the agent asks through its normal interface |
103
- | `AgentTask` | the model reasons; the result must be schema-valid JSON |
104
- | `RunCommand` | **yskill executes it itself** results are observed fact, not transcription |
105
- | `Require` | a claim bound to evidence; failure makes completion structurally unreachable |
106
- | `Complete` / `Blocked` / `Refused` | honest terminals, always recorded |
208
+ | `runCommand` | Execute a command and record its exit code and output. |
209
+ | `agentTask` | Ask the coding agent for schema-valid JSON. |
210
+ | `askUser` | Request an explicit human decision. |
211
+ | `require` | Bind a required claim to recorded evidence. |
212
+ | `blocked` / `refused` | Stop honestly when work cannot or must not continue. |
213
+
214
+ See the [primitive guides](docs/primitives/README.md) and
215
+ [runtime reference](docs/reference/cli.md) for the full contract.
107
216
 
108
- ## Four languages, one execution contract
217
+ ## Languages and coding agents
109
218
 
110
- Write the skill workflow in Go, TypeScript, Python, or Rust. Every SDK
111
- implements the same certified execution contract, and the conformance suite
112
- (`internal/conformance`) runs the same program in all four languages and
113
- asserts identical observable behavior. The language-neutral schemas are
114
- documented in the [runtime reference](docs/reference/sdk-parity.md).
219
+ All four SDKs implement the same execution contract. The conformance suite runs
220
+ the same program in every language and compares observable behavior.
115
221
 
116
- | language | SDK | example |
222
+ | Language | SDK | Example |
117
223
  |---|---|---|
118
- | Go | `sdk/yield` | `examples/investigate` — bounded hypothesis loop |
119
- | TypeScript | `sdk/typescript` (`@operatorstack/yield`) | `examples/release-checklist` — human-gated deploy |
120
- | Python | `sdk/python` (`yieldskill`) | `examples/env-doctor` — probe, branch, resume after the human |
121
- | Rust | `sdk/rust` (`yieldskill`) | `examples/data-migration` — dry-run → approve → apply → verify |
122
-
123
- Skills declare their language and runner in `skill.json`:
124
- `{"version": 1, "language": "typescript", "run": ["node", "main.ts"]}`.
125
-
126
- ## Ten skill workflows, every language
127
-
128
- The [example library](examples/library/) implements ten common skill workflows
129
- independently in all four SDKs: branch review, failure
130
- investigation, web QA, package release, issue triage, CI repair, dependency
131
- upgrade, database migration, security audit, and iOS publishing.
132
-
133
- Each language has the same skill workflow, a thin adapter, and a scripted
134
- fixture. Start from the work you already do instead of starting from a
135
- framework tutorial.
136
-
137
- ## Documentation
138
-
139
- Start with [what a skill workflow is](docs/skill-workflows.md), then build one
140
- with the [ten-minute TypeScript quickstart](docs/quickstart.md). Continue with
141
- the documentation for your job:
142
-
143
- - [primitive guides](docs/primitives/README.md) — commands, model work,
144
- human input, evidence gates, and outcomes;
145
- - [tutorials](docs/tutorials/README.md) — review, approval, environment
146
- repair, bounded debugging, and migration;
147
- - [examples](docs/examples.md) — working programs in all four languages;
148
- - [coding-agent setup](docs/agent-setup.md) — register one skill workflow with the
149
- agents used by the project;
150
- - [Agent Plugins and Yield](docs/agent-plugins.md) — where portable packaging ends
151
- and workflow execution begins;
152
- - [test workflow effects](docs/testing-fixtures.md) — deterministic fixture
153
- setup, response effects, standard-input JSON, and cleanup;
154
- - [evaluations](evals/README.md) — first-party workflow conformance and runtime
155
- invariant results, including the exact claim boundary;
156
- - [convert an existing skill](docs/convert-existing-skill.md) — move
157
- control flow into code without claiming that fixture execution proves
158
- every reading of the original prose;
159
- - [CLI and runtime reference](docs/reference/cli.md).
160
-
161
- ## Try it
224
+ | TypeScript | [`@operatorstack/yield`](sdk/typescript/) | [`release-checklist`](examples/release-checklist/) |
225
+ | Python | [`yieldskill`](sdk/python/) | [`env-doctor`](examples/env-doctor/) |
226
+ | Go | [`sdk/yield`](sdk/yield/) | [`investigate`](examples/investigate/) |
227
+ | Rust | [`yieldskill`](sdk/rust/) | [`data-migration`](examples/data-migration/) |
162
228
 
163
- ```
164
- go build -o yskill ./cmd/yskill
165
- ./yskill test examples/library/typescript/review-branch
166
- ./yskill test examples/library/python/review-branch
167
- ./yskill test examples/library/go/review-branch
168
- ./yskill test examples/library/rust/review-branch
169
- YSKILL="$PWD/yskill" bash ./examples/library/test-all.sh
170
- ./yskill test examples/investigate # Go: scripted fixture run to completion
171
- ./yskill test examples/release-checklist # TypeScript (Node >= 23.6)
172
- ./yskill test examples/env-doctor # Python 3.10+
173
- ./yskill test examples/data-migration # Rust (cargo)
174
- ./yskill run examples/investigate # prints the first operation envelope
175
- ./yskill init my-skill --description "Run this skill workflow when ..."
176
- ./yskill register my-skill --agent codex # write a thin project adapter
177
- ./yskill doctor my-skill --agent codex # verify package + adapter wiring
178
- ```
229
+ Cursor, Codex, and Claude Code are verified integrations. Yield also includes
230
+ registry-backed project paths for 73 more coding agents. Those paths support
231
+ explicit registration; they are not presented as end-to-end verified.
232
+
233
+ Run `yskill agents` to inspect the pinned registry and available project paths.
234
+
235
+ ## Guarantees and limits
179
236
 
180
- The reference skill, `examples/investigate`, encodes an investigation
181
- discipline in code: at least three hypotheses, cheapest-to-disprove
182
- first, at most three failed attempts, completion requires a causal chain
183
- — or an honest `Blocked` at the frontier.
237
+ Yield provides deterministic control flow, typed requests and responses,
238
+ persistent run state, replay with divergence detection, stale and duplicate
239
+ response rejection, and evidence-bound completion.
184
240
 
185
- ## What it guarantees and what it doesn't
241
+ Schema validity is not truth. Yield cannot prove that an agent performed only
242
+ the requested work. `runCommand` is different: the Yield CLI executes the
243
+ command, so the recorded exit code and output are observed facts.
186
244
 
187
- Guaranteed: deterministic control flow, typed requests/responses,
188
- persistent state, replay (divergence fails loudly), stale/duplicate
189
- rejection, evidence-bound completion.
245
+ Yield is not a daemon, hosted runtime, workflow DSL, marketplace, new agent
246
+ loop, multi-agent orchestrator, or security sandbox.
190
247
 
191
- Not guaranteed: that the agent performed *only* the requested operation,
192
- or that a schema-valid `agent_task` result is true — schema validity is
193
- not truth. `RunCommand` is the exception by construction: commands are
194
- executed by the Yield CLI, so exit codes and output enter the log as
195
- observed fact. Runtime and conformance tests enforce these guarantees.
248
+ ## Documentation and development
196
249
 
197
- ## What it is not
250
+ - [Read the public documentation](https://yield.operatorstack.systems/docs/)
251
+ - [What a skill workflow is](docs/skill-workflows.md)
252
+ - [Ten-minute TypeScript quickstart](docs/quickstart.md)
253
+ - [Working examples in all four languages](docs/examples.md)
254
+ - [Coding-agent setup](docs/agent-setup.md)
255
+ - [Testing workflow effects](docs/testing-fixtures.md)
256
+ - [Guarantees and evaluation results](evals/README.md)
257
+
258
+ Run the main checks from the repository root:
259
+
260
+ ```bash
261
+ go test ./...
262
+ npm run test:release
263
+ ```
198
264
 
199
- Not a daemon, not a hosted runtime, not a workflow DSL, not a
200
- marketplace, not a new agent loop, not a multi-agent orchestrator, not a
201
- security sandbox.
265
+ The [example library](examples/library/) contains ten common workflows in all
266
+ four SDKs, including code review, failure investigation, CI repair, dependency
267
+ updates, database migration, security audit, and package release.
202
268
 
203
269
  ---
204
270
 
205
- This is Yield's canonical source repository. Changes, verification, release
206
- intent, and publishing control all live here. MIT licensed.
271
+ Yield is MIT licensed. This repository contains its canonical source and
272
+ versioned technical documentation.
@@ -0,0 +1,13 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60" role="img" aria-labelledby="title">
2
+ <title id="title">Yield</title>
3
+ <defs>
4
+ <linearGradient id="band" x1="0" y1="0" x2="1" y2="1">
5
+ <stop offset="0" stop-color="#0000ee"/>
6
+ <stop offset="1" stop-color="#277168"/>
7
+ </linearGradient>
8
+ </defs>
9
+ <rect x="1" y="1" width="58" height="58" rx="12" fill="#fbfbfb" stroke="#d7d7d1" stroke-width="2"/>
10
+ <path d="M7 20h17M36 40h17" fill="none" stroke="#0a0a0a" stroke-width="5"/>
11
+ <path d="M22 12h17l2 7v22H24l-2-7Z" fill="url(#band)"/>
12
+ <path d="m34 20-6 14" fill="none" stroke="#fbfbfb" stroke-width="4"/>
13
+ </svg>
package/package.json CHANGED
@@ -1,13 +1,14 @@
1
1
  {
2
2
  "name": "@operatorstack/yield",
3
- "version": "0.1.30",
3
+ "version": "0.1.32",
4
4
  "description": "Yield skill-program SDK for TypeScript: turn SKILL.md workflows into resumable programs.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "files": [
8
8
  "bin",
9
9
  "dist",
10
- "src"
10
+ "src",
11
+ "assets"
11
12
  ],
12
13
  "bin": {
13
14
  "yskill": "bin/yskill.mjs"
@@ -32,7 +33,7 @@
32
33
  "url": "git+https://github.com/operatorstack/yield.git",
33
34
  "directory": "sdk/typescript"
34
35
  },
35
- "homepage": "https://github.com/operatorstack/yield#readme",
36
+ "homepage": "https://yield.operatorstack.systems/",
36
37
  "bugs": {
37
38
  "url": "https://github.com/operatorstack/yield/issues"
38
39
  },
@@ -49,11 +50,11 @@
49
50
  "registry": "https://registry.npmjs.org/"
50
51
  },
51
52
  "optionalDependencies": {
52
- "@operatorstack/yield-darwin-amd64": "0.1.30",
53
- "@operatorstack/yield-darwin-arm64": "0.1.30",
54
- "@operatorstack/yield-linux-amd64": "0.1.30",
55
- "@operatorstack/yield-linux-arm64": "0.1.30",
56
- "@operatorstack/yield-windows-amd64": "0.1.30",
57
- "@operatorstack/yield-windows-arm64": "0.1.30"
53
+ "@operatorstack/yield-darwin-amd64": "0.1.32",
54
+ "@operatorstack/yield-darwin-arm64": "0.1.32",
55
+ "@operatorstack/yield-linux-amd64": "0.1.32",
56
+ "@operatorstack/yield-linux-arm64": "0.1.32",
57
+ "@operatorstack/yield-windows-amd64": "0.1.32",
58
+ "@operatorstack/yield-windows-arm64": "0.1.32"
58
59
  }
59
60
  }