@operatorstack/yield 0.1.29 → 0.1.31
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/LICENSE +21 -0
- package/README.md +254 -0
- package/assets/yield-mark.svg +13 -0
- package/package.json +22 -10
- package/src/index.ts +1 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Operator Stack
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://yield.operatorstack.systems/">
|
|
3
|
+
<img src="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&style=flat-square&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="docs/README.md">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 -->
|
|
95
|
+
|
|
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/).
|
|
100
|
+
|
|
101
|
+
## Use Yield in four steps
|
|
102
|
+
|
|
103
|
+
### 1. Install Yield
|
|
104
|
+
|
|
105
|
+
Install the TypeScript SDK and its repository-local CLI in your project:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npm install --save-exact @operatorstack/yield
|
|
109
|
+
npm exec -- yskill --version
|
|
110
|
+
```
|
|
111
|
+
|
|
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.
|
|
115
|
+
|
|
116
|
+
### 2. Create the workflow
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
npm exec -- yskill init skills/release \
|
|
120
|
+
--language typescript \
|
|
121
|
+
--description "Test, review, approve, publish, and verify a package."
|
|
122
|
+
```
|
|
123
|
+
|
|
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
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
npm exec -- yskill doctor skills/release --test
|
|
146
|
+
```
|
|
147
|
+
|
|
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.
|
|
150
|
+
|
|
151
|
+
### 4. Register and use the skill
|
|
152
|
+
|
|
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
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Select verified agents explicitly when you do not want automatic detection:
|
|
161
|
+
|
|
162
|
+
```bash
|
|
163
|
+
npm exec -- yskill register skills/release \
|
|
164
|
+
--agent cursor,codex,claude-code
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
If all three are selected, Yield creates these generated files:
|
|
168
|
+
|
|
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. Start a new agent session after registration,
|
|
177
|
+
then invoke `/release` where slash skills are supported or ask the agent to use
|
|
178
|
+
the release skill.
|
|
179
|
+
|
|
180
|
+
## How Yield runs and resumes
|
|
181
|
+
|
|
182
|
+
1. Your workflow emits one typed operation.
|
|
183
|
+
2. Yield records the request and exits. It does not run a daemon.
|
|
184
|
+
3. The coding agent, user, or CLI supplies the result.
|
|
185
|
+
4. Yield resumes from the journal and replays the program to the next operation.
|
|
186
|
+
|
|
187
|
+
If replay produces a different operation, the run fails instead of silently
|
|
188
|
+
forking. Every side effect crosses one of these primitives:
|
|
189
|
+
|
|
190
|
+
| Primitive | Purpose |
|
|
191
|
+
|---|---|
|
|
192
|
+
| `runCommand` | Execute a command and record its exit code and output. |
|
|
193
|
+
| `agentTask` | Ask the coding agent for schema-valid JSON. |
|
|
194
|
+
| `askUser` | Request an explicit human decision. |
|
|
195
|
+
| `require` | Bind a required claim to recorded evidence. |
|
|
196
|
+
| `blocked` / `refused` | Stop honestly when work cannot or must not continue. |
|
|
197
|
+
|
|
198
|
+
See the [primitive guides](docs/primitives/README.md) and
|
|
199
|
+
[runtime reference](docs/reference/cli.md) for the full contract.
|
|
200
|
+
|
|
201
|
+
## Languages and coding agents
|
|
202
|
+
|
|
203
|
+
All four SDKs implement the same execution contract. The conformance suite runs
|
|
204
|
+
the same program in every language and compares observable behavior.
|
|
205
|
+
|
|
206
|
+
| Language | SDK | Example |
|
|
207
|
+
|---|---|---|
|
|
208
|
+
| TypeScript | [`@operatorstack/yield`](sdk/typescript/) | [`release-checklist`](examples/release-checklist/) |
|
|
209
|
+
| Python | [`yieldskill`](sdk/python/) | [`env-doctor`](examples/env-doctor/) |
|
|
210
|
+
| Go | [`sdk/yield`](sdk/yield/) | [`investigate`](examples/investigate/) |
|
|
211
|
+
| Rust | [`yieldskill`](sdk/rust/) | [`data-migration`](examples/data-migration/) |
|
|
212
|
+
|
|
213
|
+
Cursor, Codex, and Claude Code are verified integrations. Yield also includes
|
|
214
|
+
registry-backed project paths for 73 more coding agents. Those paths support
|
|
215
|
+
explicit registration; they are not presented as end-to-end verified.
|
|
216
|
+
|
|
217
|
+
Run `yskill agents` to inspect the pinned registry and available project paths.
|
|
218
|
+
|
|
219
|
+
## Guarantees and limits
|
|
220
|
+
|
|
221
|
+
Yield provides deterministic control flow, typed requests and responses,
|
|
222
|
+
persistent run state, replay with divergence detection, stale and duplicate
|
|
223
|
+
response rejection, and evidence-bound completion.
|
|
224
|
+
|
|
225
|
+
Schema validity is not truth. Yield cannot prove that an agent performed only
|
|
226
|
+
the requested work. `runCommand` is different: the Yield CLI executes the
|
|
227
|
+
command, so the recorded exit code and output are observed facts.
|
|
228
|
+
|
|
229
|
+
Yield is not a daemon, hosted runtime, workflow DSL, marketplace, new agent
|
|
230
|
+
loop, multi-agent orchestrator, or security sandbox.
|
|
231
|
+
|
|
232
|
+
## Documentation and development
|
|
233
|
+
|
|
234
|
+
- [What a skill workflow is](docs/skill-workflows.md)
|
|
235
|
+
- [Ten-minute TypeScript quickstart](docs/quickstart.md)
|
|
236
|
+
- [Working examples in all four languages](docs/examples.md)
|
|
237
|
+
- [Coding-agent setup](docs/agent-setup.md)
|
|
238
|
+
- [Testing workflow effects](docs/testing-fixtures.md)
|
|
239
|
+
- [Guarantees and evaluation results](evals/README.md)
|
|
240
|
+
|
|
241
|
+
Run the main checks from the repository root:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
go test ./...
|
|
245
|
+
npm run test:release
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
The [example library](examples/library/) contains ten common workflows in all
|
|
249
|
+
four SDKs, including code review, failure investigation, CI repair, dependency
|
|
250
|
+
updates, database migration, security audit, and package release.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
Yield is MIT licensed. This repository is its canonical source.
|
|
@@ -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.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.31",
|
|
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"
|
|
@@ -29,20 +30,31 @@
|
|
|
29
30
|
},
|
|
30
31
|
"repository": {
|
|
31
32
|
"type": "git",
|
|
32
|
-
"url": "https://github.com/operatorstack/yield.git",
|
|
33
|
+
"url": "git+https://github.com/operatorstack/yield.git",
|
|
33
34
|
"directory": "sdk/typescript"
|
|
34
35
|
},
|
|
36
|
+
"homepage": "https://yield.operatorstack.systems/",
|
|
37
|
+
"bugs": {
|
|
38
|
+
"url": "https://github.com/operatorstack/yield/issues"
|
|
39
|
+
},
|
|
40
|
+
"keywords": [
|
|
41
|
+
"agent",
|
|
42
|
+
"skills",
|
|
43
|
+
"workflow",
|
|
44
|
+
"resumable",
|
|
45
|
+
"cli"
|
|
46
|
+
],
|
|
35
47
|
"publishConfig": {
|
|
36
48
|
"access": "public",
|
|
37
49
|
"provenance": true,
|
|
38
50
|
"registry": "https://registry.npmjs.org/"
|
|
39
51
|
},
|
|
40
52
|
"optionalDependencies": {
|
|
41
|
-
"@operatorstack/yield-darwin-amd64": "0.1.
|
|
42
|
-
"@operatorstack/yield-darwin-arm64": "0.1.
|
|
43
|
-
"@operatorstack/yield-linux-amd64": "0.1.
|
|
44
|
-
"@operatorstack/yield-linux-arm64": "0.1.
|
|
45
|
-
"@operatorstack/yield-windows-amd64": "0.1.
|
|
46
|
-
"@operatorstack/yield-windows-arm64": "0.1.
|
|
53
|
+
"@operatorstack/yield-darwin-amd64": "0.1.31",
|
|
54
|
+
"@operatorstack/yield-darwin-arm64": "0.1.31",
|
|
55
|
+
"@operatorstack/yield-linux-amd64": "0.1.31",
|
|
56
|
+
"@operatorstack/yield-linux-arm64": "0.1.31",
|
|
57
|
+
"@operatorstack/yield-windows-amd64": "0.1.31",
|
|
58
|
+
"@operatorstack/yield-windows-arm64": "0.1.31"
|
|
47
59
|
}
|
|
48
60
|
}
|
package/src/index.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// Yield skill-program SDK for TypeScript (yield.v1).
|
|
2
2
|
//
|
|
3
|
-
// Implements the
|
|
3
|
+
// Implements the tested SDK execution contract (see ir/README.md):
|
|
4
4
|
// load the journal, replay recorded operations with a digest comparison at
|
|
5
5
|
// EVERY replayed step before consuming its response, emit exactly one
|
|
6
6
|
// program output (request | terminal | diverged) on stdout, then exit.
|