@dreamlake/dreamlake-cli 0.92.0 → 0.94.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/dist/cli/help-examples.generated.js +7 -2
- package/dist/cli/queues/index.d.ts +11 -0
- package/dist/cli/queues/index.js +71 -0
- package/dist/cli/runnable/bound-target.d.ts +73 -0
- package/dist/cli/runnable/bound-target.js +211 -0
- package/dist/cli/runnable/bound.d.ts +88 -0
- package/dist/cli/runnable/bound.js +347 -0
- package/dist/cli/runnable/index.js +2 -0
- package/dist/cli/skill/index.d.ts +30 -1
- package/dist/cli/skill/index.js +261 -103
- package/dist/cli/skill/manifest.d.ts +6 -0
- package/dist/cli/skill/manifest.js +15 -0
- package/dist/cli/skill/prefs.d.ts +6 -0
- package/dist/cli/skill/prefs.js +21 -4
- package/dist/cli/version.d.ts +1 -1
- package/dist/cli/version.js +1 -1
- package/package.json +9 -9
|
@@ -0,0 +1,347 @@
|
|
|
1
|
+
// `dreamlake runnable bind | execute | execution-receipt` — a registered UDF
|
|
2
|
+
// pinned to ONE configured snapshot and ONE locked runtime, executed on a
|
|
3
|
+
// queue through the existing configured-snapshot runner.
|
|
4
|
+
//
|
|
5
|
+
// bind registry UDF version + control-plane CodeRepo → RepoSnapshot +
|
|
6
|
+
// immutable execution binding (exec/NS/NAME@EXECUTION_DIGEST)
|
|
7
|
+
// execute one attempt of one task, under a stable invocation ID
|
|
8
|
+
// execution-receipt read that attempt's durable result; never submits
|
|
9
|
+
//
|
|
10
|
+
// The registry checks ownership and reference consistency; the SDK worker
|
|
11
|
+
// (dreamlake.lakeshore.bound) checks the delivered archive, lock and runtime.
|
|
12
|
+
// This file computes the same canonical bytes as both — parity is pinned by
|
|
13
|
+
// the shared bound_vectors.json fixture.
|
|
14
|
+
//
|
|
15
|
+
// IDENTITIES, three and never interchangeable: the execution digest (what
|
|
16
|
+
// runs), the task key (digest + queue + timeout + inputs: the business task)
|
|
17
|
+
// and the invocation ID (one attempt). A lost response is recovered by
|
|
18
|
+
// repeating the SAME command: same attempt, same ID, same bytes, which the
|
|
19
|
+
// control plane replays. `--attempt N` is a deliberate new attempt.
|
|
20
|
+
import { createHash } from "node:crypto";
|
|
21
|
+
import { readFileSync } from "node:fs";
|
|
22
|
+
import { HttpError, requestJson } from "../client.js";
|
|
23
|
+
import { resolveRemote, resolveToken } from "../config.js";
|
|
24
|
+
import { emitJson, fail, ok } from "../helpers.js";
|
|
25
|
+
import { callBridge, resolveServer } from "../python.js";
|
|
26
|
+
import { pinnedReference } from "./run.js";
|
|
27
|
+
import { runBindViaDreamLake, runTargetedCommand } from "./bound-target.js";
|
|
28
|
+
export const BINDING_PROTOCOL = "dreamlake-execution-binding-v1";
|
|
29
|
+
export const RUNNER_PROTOCOL = "dreamlake-bound-udf-v1";
|
|
30
|
+
export const TASK_PROTOCOL = "dreamlake-bound-task-v1";
|
|
31
|
+
export const RUNTIME_ENVIRONMENT = "uv-sync-locked-v1";
|
|
32
|
+
const OID = /^[a-f0-9]{24}$/;
|
|
33
|
+
const HEX64 = /^[a-f0-9]{64}$/;
|
|
34
|
+
const VERSION = /^\d+\.\d+\.\d+$/;
|
|
35
|
+
const QUEUE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
|
|
36
|
+
const INVOCATION = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
|
|
37
|
+
const seg = encodeURIComponent;
|
|
38
|
+
const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
|
39
|
+
export const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");
|
|
40
|
+
/** Same bytes as Python json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=True). */
|
|
41
|
+
export function canonical(value, depth = 0) {
|
|
42
|
+
if (depth > 64)
|
|
43
|
+
throw new Error("JSON nesting is too deep");
|
|
44
|
+
if (value === null || typeof value === "boolean")
|
|
45
|
+
return JSON.stringify(value);
|
|
46
|
+
if (typeof value === "string")
|
|
47
|
+
return ascii(value);
|
|
48
|
+
if (typeof value === "number") {
|
|
49
|
+
if (!Number.isSafeInteger(value))
|
|
50
|
+
throw new Error("Only safe integers are canonical; encode other numbers as strings");
|
|
51
|
+
return String(value);
|
|
52
|
+
}
|
|
53
|
+
if (Array.isArray(value))
|
|
54
|
+
return `[${value.map(v => canonical(v, depth + 1)).join(",")}]`;
|
|
55
|
+
if (object(value)) {
|
|
56
|
+
const keys = Object.keys(value);
|
|
57
|
+
if (keys.some(k => !/^[\x00-\x7f]*$/.test(k)))
|
|
58
|
+
throw new Error("JSON object keys must be ASCII");
|
|
59
|
+
return `{${keys.sort().map(k => `${ascii(k)}:${canonical(value[k], depth + 1)}`).join(",")}}`;
|
|
60
|
+
}
|
|
61
|
+
throw new Error(`${typeof value} is not JSON`);
|
|
62
|
+
}
|
|
63
|
+
const ascii = (s) => JSON.stringify(s).replace(/[\u007f-]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
|
|
64
|
+
/** First dreamlake-lakeshore release with the bound bridge commands. */
|
|
65
|
+
export const MIN_BOUND_SDK = "0.5.1";
|
|
66
|
+
// An older SDK's argparse rejects the unknown subcommand with exit 2, which the
|
|
67
|
+
// generic bridge reports as a CLI bug. Name the real cause: the installed SDK.
|
|
68
|
+
function boundBridge(command, argv, deps) {
|
|
69
|
+
const out = callBridge(command, argv, deps);
|
|
70
|
+
if (!out.ok && out.kind === "BridgeArgvError" && out.message.includes(`invalid choice: '${command}'`))
|
|
71
|
+
return { ok: false, message: `the installed dreamlake-lakeshore has no bridge command ${command}; bound executions need ` +
|
|
72
|
+
`dreamlake-lakeshore>=${MIN_BOUND_SDK} on this machine and on the worker — ` +
|
|
73
|
+
`pip install -U "dreamlake-lakeshore>=${MIN_BOUND_SDK}" in the interpreter the CLI uses (DREAMLAKE_PYTHON)` };
|
|
74
|
+
return out;
|
|
75
|
+
}
|
|
76
|
+
/** WHATWG origin, the spelling the SDK bridge compares against. */
|
|
77
|
+
export function originOf(server) {
|
|
78
|
+
const url = new URL(server);
|
|
79
|
+
if (!["http:", "https:"].includes(url.protocol))
|
|
80
|
+
throw new Error(`Not an http(s) control-plane URL: ${server}`);
|
|
81
|
+
return url.origin;
|
|
82
|
+
}
|
|
83
|
+
export function executionReference(ref) {
|
|
84
|
+
const m = /^exec\/([^/]+)\/([^/@]+)@([a-f0-9]{64})$/.exec(ref);
|
|
85
|
+
if (!m)
|
|
86
|
+
throw new Error("Use exec/NAMESPACE/NAME@EXECUTION_DIGEST");
|
|
87
|
+
return { namespace: m[1], name: m[2], digest: m[3] };
|
|
88
|
+
}
|
|
89
|
+
/** Registry reads + checks that need no archive. Mirrors server-side rules. */
|
|
90
|
+
export function checkRegisteredVersion(ref, head, version, repo) {
|
|
91
|
+
const pin = pinnedReference(ref);
|
|
92
|
+
if (!object(head) || head.kind !== "udf" || head.name !== pin.name || !OID.test(head.id) || !OID.test(head.namespaceId) ||
|
|
93
|
+
!object(version) || !OID.test(version.id) || version.runnableId !== head.id || version.version !== pin.version)
|
|
94
|
+
throw new Error("Registry identity mismatch");
|
|
95
|
+
if (typeof version.source !== "string" || sha256(version.source) !== pin.version)
|
|
96
|
+
throw new Error("Registered source digest mismatch");
|
|
97
|
+
const meta = version.metadata;
|
|
98
|
+
if (!object(meta) || !OID.test(meta.repo_id) || !object(repo) || repo.id !== meta.repo_id || repo.namespaceId !== head.namespaceId)
|
|
99
|
+
throw new Error("Version needs version-owned repo_id metadata for this namespace's repository");
|
|
100
|
+
if (typeof meta.entrypoint !== "string" || typeof meta.source_file !== "string" ||
|
|
101
|
+
meta.source_file !== meta.entrypoint.split(":")[0].replaceAll(".", "/") + ".py")
|
|
102
|
+
throw new Error("Version needs matching source_file and module:function entrypoint metadata");
|
|
103
|
+
return { pin, meta };
|
|
104
|
+
}
|
|
105
|
+
export function buildBinding(args) {
|
|
106
|
+
const { head, version, repo, snapshotRow, described, sourcePath, project, pythonVersion } = args;
|
|
107
|
+
const cr = described.codeRepo, archive = described.archive, files = described.files;
|
|
108
|
+
const lockPath = project === "." ? "uv.lock" : `${project}/uv.lock`;
|
|
109
|
+
const pyprojectPath = project === "." ? "pyproject.toml" : `${project}/pyproject.toml`;
|
|
110
|
+
return {
|
|
111
|
+
protocol: BINDING_PROTOCOL,
|
|
112
|
+
namespace: { id: head.namespaceId },
|
|
113
|
+
udf: { runnableId: head.id, name: head.name, versionId: version.id, version: version.version,
|
|
114
|
+
sourceFile: version.metadata.source_file, entrypoint: version.metadata.entrypoint, archivePath: sourcePath },
|
|
115
|
+
repo: { id: repo.id, remote: repo.remote },
|
|
116
|
+
repoSnapshot: { id: snapshotRow.id },
|
|
117
|
+
archive: { sha256: archive.sha256, format: archive.format },
|
|
118
|
+
controlPlane: { origin: described.origin, namespace: described.namespace, codeRepoId: cr.id, commit: cr.commit,
|
|
119
|
+
archiveKey: cr.archiveKey, storageName: cr.storageName },
|
|
120
|
+
runtime: { environment: RUNTIME_ENVIRONMENT, implementation: "CPython", pythonVersion, projectPath: project,
|
|
121
|
+
lockSha256: files[lockPath], pyprojectSha256: files[pyprojectPath] },
|
|
122
|
+
runner: { protocol: RUNNER_PROTOCOL },
|
|
123
|
+
};
|
|
124
|
+
}
|
|
125
|
+
export async function runBind(ref, opts, deps = {}) {
|
|
126
|
+
try {
|
|
127
|
+
const pin = pinnedReference(ref);
|
|
128
|
+
if (!OID.test(opts.snapshot))
|
|
129
|
+
throw new Error("--snapshot must be the 24-hex configured CodeRepo id printed by `dreamlake snapshot`");
|
|
130
|
+
const server = resolveServer(opts.server);
|
|
131
|
+
if (!server)
|
|
132
|
+
throw new Error("no control plane — pass --server or set LAKESHORE_URL");
|
|
133
|
+
const cpNamespace = opts.cpNamespace || process.env.LAKESHORE_NAMESPACE || pin.namespace;
|
|
134
|
+
const token = resolveToken();
|
|
135
|
+
if (!token)
|
|
136
|
+
throw new Error("Log in to DreamLake first");
|
|
137
|
+
const remote = resolveRemote();
|
|
138
|
+
const base = `/namespaces/${seg(pin.namespace)}`;
|
|
139
|
+
const get = (path) => requestJson(remote, path, { token, redirect: "error" });
|
|
140
|
+
const head = await get(`${base}/runnables/${seg(pin.name)}`);
|
|
141
|
+
const version = await get(`${base}/runnables/${seg(pin.name)}/versions/${pin.version}`);
|
|
142
|
+
if (!object(version?.metadata) || !OID.test(version.metadata.repo_id))
|
|
143
|
+
throw new Error("Version has no version-owned repository binding; register it with a .dreamrc repo first");
|
|
144
|
+
const repo = await get(`${base}/repos/${version.metadata.repo_id}`);
|
|
145
|
+
const { meta } = checkRegisteredVersion(ref, head, version, repo);
|
|
146
|
+
const project = opts.project.replace(/\/+$/, "") || ".";
|
|
147
|
+
const sourcePath = opts.sourcePath ?? (project === "." ? meta.source_file : `${project}/${meta.source_file}`);
|
|
148
|
+
// Content comes from the STORED archive, downloaded and verified by the SDK.
|
|
149
|
+
const out = boundBridge("describe-snapshot", ["--server", server, "--namespace", cpNamespace, "--snapshot", opts.snapshot,
|
|
150
|
+
"--project", project, "--source-path", sourcePath], { ...deps, quiet: opts.json ?? deps.quiet });
|
|
151
|
+
if (!out.ok)
|
|
152
|
+
throw new Error(out.message);
|
|
153
|
+
const described = out.data;
|
|
154
|
+
if (described.files?.[sourcePath] !== pin.version)
|
|
155
|
+
throw new Error(`${sourcePath} in snapshot ${opts.snapshot} is not the registered source ${pin.version}`);
|
|
156
|
+
const pythonVersion = opts.python ?? described.pythonVersion;
|
|
157
|
+
if (typeof pythonVersion !== "string" || !VERSION.test(pythonVersion))
|
|
158
|
+
throw new Error("The runtime needs an exact X.Y.Z Python version: commit it in <project>/.python-version or pass --python");
|
|
159
|
+
if (described.pythonVersion && described.pythonVersion !== pythonVersion)
|
|
160
|
+
throw new Error(`--python ${pythonVersion} disagrees with the snapshot's .python-version ${described.pythonVersion}`);
|
|
161
|
+
const cr = described.codeRepo;
|
|
162
|
+
const snapshotBody = { commit: described.archive.sha256, backend: "s3", archiveKey: cr.archiveKey,
|
|
163
|
+
storageName: cr.storageName, sizeBytes: described.archive.sizeBytes,
|
|
164
|
+
metadata: { controlPlane: { origin: described.origin, namespace: described.namespace, codeRepoId: cr.id } } };
|
|
165
|
+
if (opts.dryRun) {
|
|
166
|
+
const preview = buildBinding({ head, version, repo, snapshotRow: { id: "(registered on bind)" }, described,
|
|
167
|
+
sourcePath, project, pythonVersion });
|
|
168
|
+
emitJson({ status: "dry-run", repoSnapshot: snapshotBody, binding: preview });
|
|
169
|
+
return 0;
|
|
170
|
+
}
|
|
171
|
+
const snapshotRow = await requestJson(remote, `${base}/repos/${repo.id}/snapshots`, { method: "POST", token, json: snapshotBody });
|
|
172
|
+
if (!object(snapshotRow) || !OID.test(snapshotRow.id) || snapshotRow.commit !== snapshotBody.commit ||
|
|
173
|
+
snapshotRow.backend !== "s3" || snapshotRow.archiveKey !== cr.archiveKey || snapshotRow.storageName !== cr.storageName)
|
|
174
|
+
throw new Error("An existing RepoSnapshot for this archive differs from the control-plane CodeRepo; inspect it before binding");
|
|
175
|
+
const binding = buildBinding({ head, version, repo, snapshotRow, described, sourcePath, project, pythonVersion });
|
|
176
|
+
const text = canonical(binding);
|
|
177
|
+
const digest = sha256(text);
|
|
178
|
+
const stored = await requestJson(remote, `${base}/runnables/${seg(head.id)}/executions`, { method: "POST", token, json: { binding, executionDigest: digest } });
|
|
179
|
+
if (stored?.executionDigest !== digest || stored?.canonical !== text)
|
|
180
|
+
throw new Error("Unexpected execution-binding receipt; inspect before retrying");
|
|
181
|
+
const execRef = `exec/${pin.namespace}/${pin.name}@${digest}`;
|
|
182
|
+
if (opts.json)
|
|
183
|
+
emitJson({ status: "bound", ref: execRef, executionDigest: digest, binding });
|
|
184
|
+
else {
|
|
185
|
+
ok(`bound ${execRef}`);
|
|
186
|
+
process.stdout.write(` archive: ${binding.archive.sha256}\n CodeRepo: ${cr.id} (${described.origin} ${described.namespace})\n` +
|
|
187
|
+
` runtime: CPython ${pythonVersion}, uv.lock ${binding.runtime.lockSha256}\n`);
|
|
188
|
+
}
|
|
189
|
+
return 0;
|
|
190
|
+
}
|
|
191
|
+
catch (e) {
|
|
192
|
+
fail(e instanceof HttpError ? e.message : e.message);
|
|
193
|
+
return 1;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
export function buildTaskRequest(digest, o) {
|
|
197
|
+
if (!QUEUE.test(o.queue))
|
|
198
|
+
throw new Error("--queue must be a queue name");
|
|
199
|
+
if (!Number.isInteger(o.timeoutSeconds) || o.timeoutSeconds < 1 || o.timeoutSeconds > 86400)
|
|
200
|
+
throw new Error("--timeout-seconds must be 1..86400");
|
|
201
|
+
if (!Number.isInteger(o.attempt) || o.attempt < 1 || o.attempt > 1000)
|
|
202
|
+
throw new Error("--attempt must be 1..1000");
|
|
203
|
+
if (!object(o.inputs))
|
|
204
|
+
throw new Error("--inputs must hold one JSON object");
|
|
205
|
+
if (Buffer.byteLength(canonical(o.inputs)) > 256 * 1024)
|
|
206
|
+
throw new Error("Inputs exceed 256 KiB");
|
|
207
|
+
const taskKey = sha256(canonical({ protocol: TASK_PROTOCOL, executionDigest: digest, queue: o.queue,
|
|
208
|
+
timeoutSeconds: o.timeoutSeconds, inputs: o.inputs }));
|
|
209
|
+
const invocationId = o.invocationId ?? `bx1-${taskKey.slice(0, 40)}-a${o.attempt}`;
|
|
210
|
+
if (!INVOCATION.test(invocationId))
|
|
211
|
+
throw new Error("--invocation-id must match [A-Za-z0-9][A-Za-z0-9_.:-]{0,127}");
|
|
212
|
+
return { protocol: TASK_PROTOCOL, executionDigest: digest, queue: o.queue, timeoutSeconds: o.timeoutSeconds,
|
|
213
|
+
inputs: o.inputs, attempt: o.attempt, taskKey, invocationId };
|
|
214
|
+
}
|
|
215
|
+
/** Read the immutable binding and prove it is the digest the ref names. */
|
|
216
|
+
export async function readBinding(ref) {
|
|
217
|
+
const r = executionReference(ref);
|
|
218
|
+
const token = resolveToken();
|
|
219
|
+
if (!token)
|
|
220
|
+
throw new Error("Log in to DreamLake first");
|
|
221
|
+
const row = await requestJson(resolveRemote(), `/namespaces/${seg(r.namespace)}/runnables/${seg(r.name)}/executions/${r.digest}`, { token, redirect: "error" });
|
|
222
|
+
if (typeof row?.canonical !== "string" || sha256(row.canonical) !== r.digest)
|
|
223
|
+
throw new Error("Registry returned a binding that does not hash to its digest");
|
|
224
|
+
const binding = JSON.parse(row.canonical);
|
|
225
|
+
if (canonical(binding) !== row.canonical || binding.protocol !== BINDING_PROTOCOL || binding.udf?.name !== r.name)
|
|
226
|
+
throw new Error("Registry binding is not a canonical binding for this runnable");
|
|
227
|
+
return { ref: r, binding, text: row.canonical };
|
|
228
|
+
}
|
|
229
|
+
function target(binding, opts) {
|
|
230
|
+
const cp = binding.controlPlane;
|
|
231
|
+
// Never default to the binding's origin: the bridge attaches the caller's
|
|
232
|
+
// control-plane token, so the caller must choose the server explicitly and
|
|
233
|
+
// the binding can only be checked against it, not redirect it.
|
|
234
|
+
const server = resolveServer(opts.server);
|
|
235
|
+
if (!server)
|
|
236
|
+
throw new Error(`no control plane — pass --server or set LAKESHORE_URL (this binding targets ${cp.origin})`);
|
|
237
|
+
if (originOf(server) !== cp.origin)
|
|
238
|
+
throw new Error(`Binding targets control plane ${cp.origin}, not ${originOf(server)}`);
|
|
239
|
+
const ns = opts.cpNamespace || cp.namespace;
|
|
240
|
+
if (ns !== cp.namespace)
|
|
241
|
+
throw new Error(`Binding targets control-plane namespace ${cp.namespace}, not ${ns}`);
|
|
242
|
+
return { server, ns };
|
|
243
|
+
}
|
|
244
|
+
function requestFrom(digest, opts) {
|
|
245
|
+
if (!opts.queue)
|
|
246
|
+
throw new Error("--queue is required: a bound execution names its queue explicitly");
|
|
247
|
+
if (!opts.inputs)
|
|
248
|
+
throw new Error("--inputs <file> is required (one JSON object)");
|
|
249
|
+
return buildTaskRequest(digest, { queue: opts.queue, inputs: JSON.parse(readFileSync(opts.inputs, "utf8")),
|
|
250
|
+
timeoutSeconds: Number(opts.timeoutSeconds ?? 3600), attempt: Number(opts.attempt ?? 1), invocationId: opts.invocationId });
|
|
251
|
+
}
|
|
252
|
+
export async function runBoundCommand(command, ref, opts, deps = {}) {
|
|
253
|
+
let request;
|
|
254
|
+
try {
|
|
255
|
+
const { binding, text } = await readBinding(ref);
|
|
256
|
+
const { server, ns } = target(binding, opts);
|
|
257
|
+
request = requestFrom(executionReference(ref).digest, opts);
|
|
258
|
+
// The recoverable identity is printed BEFORE anything is submitted.
|
|
259
|
+
process.stderr.write(`Invocation: ${request.invocationId}\nTask key: ${request.taskKey}\nAttempt: ${request.attempt}\n`);
|
|
260
|
+
const wait = command === "bound-receipt" ? Number(opts.waitSeconds ?? 0) : Number(opts.waitSeconds ?? request.timeoutSeconds + 60);
|
|
261
|
+
const out = boundBridge(command, ["--server", server, "--namespace", ns, "--binding", text,
|
|
262
|
+
"--request", canonical(request), "--timeout", String(wait),
|
|
263
|
+
...(command === "launch-bound" && opts.wait === false ? ["--no-wait"] : [])], { ...deps, quiet: opts.json ?? deps.quiet });
|
|
264
|
+
if (!out.ok)
|
|
265
|
+
throw new Error(out.message);
|
|
266
|
+
const d = out.data;
|
|
267
|
+
if (d.invocationId !== request.invocationId || d.executionDigest !== request.executionDigest || d.taskKey !== request.taskKey)
|
|
268
|
+
throw new Error("Bridge result does not belong to this request");
|
|
269
|
+
const receipt = object(d.receipt) ? d.receipt : null;
|
|
270
|
+
const status = receipt ? String(receipt.status) : command === "launch-bound" && opts.wait === false ? "submitted" : "pending";
|
|
271
|
+
const record = { status, ref, invocationId: request.invocationId, taskKey: request.taskKey, attempt: request.attempt,
|
|
272
|
+
executionDigest: request.executionDigest, queue: request.queue, receipt };
|
|
273
|
+
if (opts.json)
|
|
274
|
+
emitJson(record);
|
|
275
|
+
else {
|
|
276
|
+
ok(`${status} ${request.invocationId}`);
|
|
277
|
+
if (receipt)
|
|
278
|
+
process.stdout.write(JSON.stringify(receipt, null, 2) + "\n");
|
|
279
|
+
if (status === "pending")
|
|
280
|
+
process.stdout.write(` still running; repeat the same command to recover — do not change --attempt\n`);
|
|
281
|
+
}
|
|
282
|
+
return status === "succeeded" || status === "submitted" ? 0 : 1;
|
|
283
|
+
}
|
|
284
|
+
catch (e) {
|
|
285
|
+
fail(`${e.message}` + (request ? `\nInvocation: ${request.invocationId}; repeat the same command and inputs to recover` : ""));
|
|
286
|
+
return 1;
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
// ─── registration ────────────────────────────────────────────────────────────
|
|
290
|
+
export function registerRunnableBound(runnable) {
|
|
291
|
+
runnable.command("bind <ref>")
|
|
292
|
+
.description("bind a registered UDF version to one configured snapshot and locked runtime (immutable execution binding)")
|
|
293
|
+
.option("--snapshot <id>", "24-hex configured CodeRepo id from `dreamlake snapshot` (control-plane path)")
|
|
294
|
+
.option("--target <host>", "namespace/group/host you own: build this checkout's configured archive and upload it through DreamLake (no control-plane credential)")
|
|
295
|
+
.option("--enrollment <id>", "with --target: the host enrollment, when it has more than one")
|
|
296
|
+
.option("--config <path>", "with --target: explicit .dreamrc (default: walk up from the current directory)")
|
|
297
|
+
.requiredOption("--project <path>", "snapshot code path holding pyproject.toml, uv.lock and .python-version")
|
|
298
|
+
.option("--source-path <path>", "snapshot code path of the registered source (default: <project>/<source_file>)")
|
|
299
|
+
.option("--python <X.Y.Z>", "exact CPython version (default: <project>/.python-version in the snapshot)")
|
|
300
|
+
.option("--server <url>", "control plane base URL (default: $LAKESHORE_URL)")
|
|
301
|
+
.option("--cp-namespace <slug>", "control-plane namespace (default: $LAKESHORE_NAMESPACE, else the registry namespace)")
|
|
302
|
+
.option("--dry-run", "verify and print the binding without registry writes")
|
|
303
|
+
.option("--json", "emit JSON")
|
|
304
|
+
.action(async (ref, opts) => {
|
|
305
|
+
if (opts.target && (opts.snapshot || opts.server || opts.cpNamespace)) {
|
|
306
|
+
fail("--target uploads through DreamLake; do not combine it with --snapshot, --server or --cp-namespace");
|
|
307
|
+
process.exitCode = 1;
|
|
308
|
+
}
|
|
309
|
+
else if (opts.target)
|
|
310
|
+
process.exitCode = await runBindViaDreamLake(ref, opts);
|
|
311
|
+
else if (!opts.snapshot) {
|
|
312
|
+
fail("pass --snapshot <CodeRepo id> (control-plane path) or --target <namespace/group/host>");
|
|
313
|
+
process.exitCode = 1;
|
|
314
|
+
}
|
|
315
|
+
else
|
|
316
|
+
process.exitCode = await runBind(ref, opts);
|
|
317
|
+
});
|
|
318
|
+
for (const [name, command, description] of [
|
|
319
|
+
["execute", "launch-bound", "submit one attempt of a bound execution to a queue and wait for its receipt"],
|
|
320
|
+
["execution-receipt", "bound-receipt", "read one attempt's durable receipt without submitting"],
|
|
321
|
+
]) {
|
|
322
|
+
const c = runnable.command(`${name} <ref>`).description(description)
|
|
323
|
+
.requiredOption("--queue <name>", "queue the attempt runs on (part of the task key)")
|
|
324
|
+
.requiredOption("--inputs <file>", "one JSON object passed to the UDF (part of the task key)")
|
|
325
|
+
.option("--attempt <n>", "attempt number; a new number is a deliberate new attempt", "1")
|
|
326
|
+
.option("--invocation-id <id>", "explicit attempt ID instead of the derived bx1-<task key>-a<attempt>")
|
|
327
|
+
.option("--timeout-seconds <s>", "worker execution timeout (part of the task key)", "3600")
|
|
328
|
+
.option("--wait-seconds <s>", name === "execute" ? "client wait (default: timeout + 60)" : "client wait (default: 0, read once)")
|
|
329
|
+
.option("--server <url>", "control plane base URL (default: $LAKESHORE_URL; must equal the binding's origin)")
|
|
330
|
+
.option("--cp-namespace <slug>", "control-plane namespace (default: the binding's)")
|
|
331
|
+
.option("--target <host>", "namespace/group/host you own: run through DreamLake on that host's pinned queue (no control-plane credential)")
|
|
332
|
+
.option("--enrollment <id>", "with --target: the host enrollment, when it has more than one")
|
|
333
|
+
.option("--json", "emit JSON");
|
|
334
|
+
if (name === "execute")
|
|
335
|
+
c.option("--no-wait", "return after durable submission");
|
|
336
|
+
c.action(async (ref, opts) => {
|
|
337
|
+
if (opts.target && (opts.server || opts.cpNamespace || opts.invocationId)) {
|
|
338
|
+
fail("--target runs through DreamLake; do not combine it with --server, --cp-namespace or --invocation-id");
|
|
339
|
+
process.exitCode = 1;
|
|
340
|
+
}
|
|
341
|
+
else if (opts.target)
|
|
342
|
+
process.exitCode = await runTargetedCommand(name === "execute" ? "execute" : "receipt", ref, opts);
|
|
343
|
+
else
|
|
344
|
+
process.exitCode = await runBoundCommand(command, ref, opts);
|
|
345
|
+
});
|
|
346
|
+
}
|
|
347
|
+
}
|
|
@@ -31,6 +31,7 @@ import { resolveNamespace, resolveRemote, resolveToken } from "../config.js";
|
|
|
31
31
|
import { emitJson, fail, ok, renderTable, warn } from "../helpers.js";
|
|
32
32
|
import { namespaceFromPath, resolveRunnablePath } from "./path.js";
|
|
33
33
|
import { registerRunnableRun } from "./run.js";
|
|
34
|
+
import { registerRunnableBound } from "./bound.js";
|
|
34
35
|
// ─── shared context resolution ───────────────────────────────────────────────
|
|
35
36
|
async function ctx(nsFlag) {
|
|
36
37
|
const token = resolveToken();
|
|
@@ -457,6 +458,7 @@ export function registerRunnableCommand(program) {
|
|
|
457
458
|
.command("runnable")
|
|
458
459
|
.description("browse runnables (udf | session | agent), their versions, and import them");
|
|
459
460
|
registerRunnableRun(runnable);
|
|
461
|
+
registerRunnableBound(runnable);
|
|
460
462
|
collectionList(runnable, "list")
|
|
461
463
|
.description("list runnables in a namespace")
|
|
462
464
|
.option("--kind <kind>", "filter by lifetime: udf | session | agent")
|
|
@@ -41,6 +41,8 @@ export type SkillState =
|
|
|
41
41
|
export interface SkillResult {
|
|
42
42
|
status: SkillInstallStatus;
|
|
43
43
|
skill: string;
|
|
44
|
+
/** Which agent's copy this is. Set only when the run targets more than one agent. */
|
|
45
|
+
agent?: SkillAgent;
|
|
44
46
|
/** Release tag the payload came from; null when the source carries none. */
|
|
45
47
|
version: string | null;
|
|
46
48
|
source: SkillSourceKind | null;
|
|
@@ -79,7 +81,10 @@ export interface SkillCatalogInfo {
|
|
|
79
81
|
/** The result of `install`, `update` and `init`. */
|
|
80
82
|
export interface SkillInstallResult {
|
|
81
83
|
status: SkillInstallStatus;
|
|
84
|
+
/** The agent, when the run targets exactly one. */
|
|
82
85
|
agent?: SkillAgent;
|
|
86
|
+
/** Every agent, when the run targets more than one; `agent` is then absent. */
|
|
87
|
+
agents?: SkillAgent[];
|
|
83
88
|
scope?: SkillScope;
|
|
84
89
|
catalog?: SkillCatalogInfo;
|
|
85
90
|
/** One entry per skill, requested ones first, then `requires`. */
|
|
@@ -101,6 +106,14 @@ export interface SkillInstallResult {
|
|
|
101
106
|
export interface SkillRemoveResult {
|
|
102
107
|
status: SkillRemoveStatus;
|
|
103
108
|
agent?: SkillAgent;
|
|
109
|
+
/** Every agent, when the run targets more than one; `agent` and `target` are then absent. */
|
|
110
|
+
agents?: SkillAgent[];
|
|
111
|
+
/**
|
|
112
|
+
* Multi-agent only: one single-agent result per agent the skill was found
|
|
113
|
+
* under. An agent where the skill is absent is skipped, unless it is absent
|
|
114
|
+
* under every agent — then each absence is an error here.
|
|
115
|
+
*/
|
|
116
|
+
removals?: SkillRemoveResult[];
|
|
104
117
|
scope?: SkillScope;
|
|
105
118
|
skill?: string;
|
|
106
119
|
target?: string;
|
|
@@ -171,6 +184,20 @@ export interface SkillInstallOptions {
|
|
|
171
184
|
allowDowngrade?: boolean;
|
|
172
185
|
json?: boolean;
|
|
173
186
|
}
|
|
187
|
+
/** One agent's installed state for a list row. */
|
|
188
|
+
export interface SkillAgentInstalls {
|
|
189
|
+
project: SkillScopeState;
|
|
190
|
+
global: SkillScopeState;
|
|
191
|
+
}
|
|
192
|
+
/** A list row when more than one agent is selected: `installs` replaces `project` and `global`. */
|
|
193
|
+
export interface SkillMultiListEntry extends Omit<SkillListEntry, "project" | "global"> {
|
|
194
|
+
installs: Partial<Record<SkillAgent, SkillAgentInstalls>>;
|
|
195
|
+
}
|
|
196
|
+
/** `skill list` when more than one agent is selected. */
|
|
197
|
+
export interface SkillMultiListResult extends Omit<SkillListResult, "agent" | "skills"> {
|
|
198
|
+
agents: SkillAgent[];
|
|
199
|
+
skills?: SkillMultiListEntry[];
|
|
200
|
+
}
|
|
174
201
|
export interface SkillListOptions {
|
|
175
202
|
agent?: string;
|
|
176
203
|
refresh?: boolean;
|
|
@@ -199,6 +226,7 @@ export declare function skillTarget(scopeRoot: string, name: string, agent?: Ski
|
|
|
199
226
|
* checked against it, never against a fresh resolution.
|
|
200
227
|
*/
|
|
201
228
|
export declare function ownedTarget(dir: string, name: string): OwnedDir;
|
|
229
|
+
export declare const AGENT_ERROR = "--agent must be claude, codex, all, or a comma-separated list of them";
|
|
202
230
|
/** The command that would resolve the current invocation, `--force` and `--allow-downgrade` optional. */
|
|
203
231
|
export declare function skillCommand(verb: "install" | "update" | "remove", names: string | string[], opts: SkillInstallOptions, force: boolean, allowDowngrade?: boolean): string;
|
|
204
232
|
export declare function installCommand(skill: string | string[], opts: SkillInstallOptions, force: boolean): string;
|
|
@@ -261,7 +289,8 @@ export declare function installedSkillEntries(agent: SkillAgent, options?: ListE
|
|
|
261
289
|
export declare function runSkillList(opts: SkillListOptions): Promise<number>;
|
|
262
290
|
export interface SkillInitIO {
|
|
263
291
|
interactive: boolean;
|
|
264
|
-
agent
|
|
292
|
+
/** One agent, or several to install for each of them. */
|
|
293
|
+
agent(): Promise<SkillAgent | SkillAgent[]>;
|
|
265
294
|
global(): Promise<boolean>;
|
|
266
295
|
}
|
|
267
296
|
export declare function runSkillInit(opts: SkillInstallOptions, io?: SkillInitIO): Promise<number>;
|