@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.
@@ -8,6 +8,9 @@ export const helpExamples = {
8
8
  "artifact meta set": "# At push time:\ndreamlake artifact push ./report.html --id q1-dashboard \\\n --description \"Revenue, churn and pipeline for the quarter\" \\\n --cover ./cover.png\n\n# Or after the fact, for an artifact that already exists:\ndreamlake artifact meta set q1-dashboard --description \"Revenue, churn and pipeline\"\ndreamlake artifact meta set q1-dashboard --cover ./cover.png\ndreamlake artifact meta show q1-dashboard\n\n# Back to the automatic description / the generated cover:\ndreamlake artifact meta set q1-dashboard --clear-description --clear-cover",
9
9
  "artifact share": "# Find the dashboard you already uploaded; no new version is needed.\ndreamlake artifact list\nARTIFACT=\"q1-dashboard\" # Replace with the id from list.\ndreamlake artifact share get \"$ARTIFACT\"\n\n# Give signed-in recipients read access, then verify the returned link.\ndreamlake artifact share create \"$ARTIFACT\"\ndreamlake artifact share get \"$ARTIFACT\"\n\n# When link access is no longer needed, revoke it and verify.\ndreamlake artifact share revoke \"$ARTIFACT\"\ndreamlake artifact share get \"$ARTIFACT\"",
10
10
  "artifact visibility": "ARTIFACT=\"q1-dashboard\" # Your existing artifact id.\ndreamlake artifact visibility \"$ARTIFACT\" public\ndreamlake artifact visibility \"$ARTIFACT\" private",
11
+ "runnable bind": "dreamlake runnable bind udf/acme/recipes.process@FULL_SHA256 \\\n --snapshot CODE_REPO_ID --project recipes \\\n --server \"$LAKESHORE_URL\" --cp-namespace acme --dry-run\ndreamlake runnable bind udf/acme/recipes.process@FULL_SHA256 \\\n --snapshot CODE_REPO_ID --project recipes --server \"$LAKESHORE_URL\" --cp-namespace acme",
12
+ "runnable execute": "dreamlake runnable execute exec/acme/recipes.process@EXECUTION_DIGEST \\\n --queue cpu --inputs record.json --timeout-seconds 600 --json\ndreamlake runnable execute exec/acme/recipes.process@EXECUTION_DIGEST \\\n --queue cpu --inputs record.json --timeout-seconds 600 --attempt 2 --json",
13
+ "runnable execution-receipt": "dreamlake runnable execution-receipt exec/acme/recipes.process@EXECUTION_DIGEST \\\n --queue cpu --inputs record.json --timeout-seconds 600 --wait-seconds 30",
11
14
  "hosts": "dreamlake hosts\ndreamlake hosts --all\ndreamlake hosts -h\ndreamlake hosts list -h",
12
15
  "nymph": "dreamlake nymph\ndreamlake nymph --json",
13
16
  "nymph setup": "dreamlake nymph setup --name alice/computers/laptop --lakeshore-id CONNECTION_ID",
@@ -127,6 +130,8 @@ export const helpExamples = {
127
130
  "providers instances logs": "dreamlake providers instances logs team/333333333333333333333333 --instance POD_NAME --tail 100 --json",
128
131
  "providers instances terminate": "dreamlake providers instances terminate team/333333333333333333333333 --instance POD_NAME --request-id kube-delete-01 --json",
129
132
  "queues worker-claims": "dreamlake queues worker-claims lab WORKER_ID --namespace geyang\ndreamlake queues worker-claims lab WORKER_ID --namespace geyang --disable\ndreamlake queues worker-claims lab WORKER_ID --namespace geyang --enable --json",
133
+ "queues create": "dreamlake queues create lab fixture --namespace geyang",
134
+ "queues worker-pin": "dreamlake queues worker-pin lab WORKER_ID --namespace geyang\ndreamlake queues worker-pin lab WORKER_ID --namespace geyang --queue fixture --host geyang/dev/worker\ndreamlake queues worker-pin lab WORKER_ID --namespace geyang --clear --host geyang/dev/worker --json",
130
135
  "queues slurm clusters": "dreamlake queues slurm clusters --namespace geyang",
131
136
  "queues slurm jobs": "dreamlake queues slurm jobs CLUSTER_ID --namespace geyang\ndreamlake queues slurm jobs CLUSTER_ID --namespace geyang --details\ndreamlake queues slurm jobs CLUSTER_ID --namespace geyang --json",
132
137
  "runnable run": "dreamlake runnable run udf/NAMESPACE/NAME@FULL_SHA256 \\\n --target NAMESPACE/GROUP/HOST --enrollment-id ENROLLMENT_ID \\\n --request-id YOUR_STABLE_REQUEST_ID --inputs inputs.json --json",
@@ -177,10 +182,10 @@ export const helpExamples = {
177
182
  "sessions chat": "dreamlake sessions chat \"Which of my sessions need attention?\"\n# Allow lifecycle and messaging tools this turn:\ndreamlake sessions chat --control \"Send 'rebase on main' to the two Claude sessions working on notes\"",
178
183
  "sessions tool-calls": "dreamlake sessions tool-calls <conversation-id>",
179
184
  "dreamlake": "# Guided agent setup: choose agent and scope, install dreamlake-cli offline\ndreamlake init\n# Install more skills from the public release\ndreamlake skill install dreamlake-notes\n# Keep installed skills current\ndreamlake skill update",
180
- "init": "dreamlake init\ndreamlake init --agent codex\ndreamlake init --agent claude --global",
185
+ "init": "dreamlake init\ndreamlake init --agent codex\ndreamlake init --agent claude --global\n# Claude Code and Codex: one copy in each agent's directory\ndreamlake init --agent all --global",
181
186
  "skill": "dreamlake skill list\ndreamlake skill install dreamlake-notes\ndreamlake skill update\ndreamlake skill remove dreamlake-notes",
182
187
  "skill list": "dreamlake skill list\n# Fetch the latest catalog and show it next to the installed versions\ndreamlake skill list --refresh\ndreamlake skill list --agent codex --json",
183
- "skill install": "# The embedded dreamlake-cli skill; offline when it matches the release\ndreamlake skill install dreamlake-cli\n# A catalog skill plus whatever it requires, from the latest release\ndreamlake skill install dreamlake-notes --agent codex\n# Replace files you edited with the release copies\ndreamlake skill install dreamlake-notes --force",
188
+ "skill install": "# The embedded dreamlake-cli skill; offline when it matches the release\ndreamlake skill install dreamlake-cli\n# A catalog skill plus whatever it requires, from the latest release\ndreamlake skill install dreamlake-notes --agent codex\n# One copy for Claude Code and one for Codex\ndreamlake skill install dreamlake-notes --agent all --global\n# Replace files you edited with the release copies\ndreamlake skill install dreamlake-notes --force",
184
189
  "skill update": "# Every skill with a manifest in the selected scope\ndreamlake skill update\ndreamlake skill update dreamlake-cli --global\n# Overwrite edited files; retired files you edited are still kept\ndreamlake skill update dreamlake-notes --force\n# Go back to an older release, or replace a copy whose version cannot be ordered\ndreamlake skill update dreamlake-notes --allow-downgrade",
185
190
  "skill remove": "dreamlake skill remove dreamlake-notes\ndreamlake skill remove dreamlake-notes --agent codex --global --json",
186
191
  "vault cloud import": "# No --file: list standard candidate paths without opening their contents.\ndreamlake vault cloud import --provider aws -p alice/aws/dev\n# Explicit selections: preview names, sizes and profile metadata, without upload.\ndreamlake vault cloud import --provider aws -p alice/aws/dev \\\n --file \"$HOME/.aws/config\" --file \"$HOME/.aws/credentials\"\n# Repeat the selection with --apply to upload.\ndreamlake vault cloud import --provider aws -p alice/aws/dev \\\n --file \"$HOME/.aws/config\" --file \"$HOME/.aws/credentials\" --apply\ndreamlake vault cloud import --provider gcp -p alice/gcp/dev \\\n --file /private/config/service-account.json --apply",
@@ -1,4 +1,5 @@
1
1
  import type { Command } from "commander";
2
+ import { resolveTarget } from "../runnable/bound-target.js";
2
3
  export interface QueueOpts {
3
4
  namespace?: string;
4
5
  json?: boolean;
@@ -35,4 +36,14 @@ export interface WorkerClaimsOpts extends QueueOpts {
35
36
  disable?: boolean;
36
37
  }
37
38
  export declare function runQueuesWorkerClaims(prefix: string, workerId: string, opts: WorkerClaimsOpts): Promise<number>;
39
+ export interface WorkerPinOpts extends QueueOpts {
40
+ host?: string;
41
+ enrollment?: string;
42
+ queue?: string[];
43
+ clear?: boolean;
44
+ }
45
+ export declare function runQueuesWorkerPin(prefix: string, workerId: string, opts: WorkerPinOpts, deps?: {
46
+ resolve?: typeof resolveTarget;
47
+ }): Promise<number>;
48
+ export declare function runQueuesCreate(prefix: string, name: string, opts: QueueOpts): Promise<number>;
38
49
  export declare function registerQueuesCommand(program: Command): void;
@@ -4,6 +4,7 @@ import { input, password } from "@inquirer/prompts";
4
4
  import { HttpError, requestJson } from "../client.js";
5
5
  import { resolveNamespace, resolveRemote, resolveToken } from "../config.js";
6
6
  import { emitJson, fail, renderTable } from "../helpers.js";
7
+ import { resolveTarget } from "../runnable/bound-target.js";
7
8
  const mountInput = {
8
9
  get interactive() { return !!process.stdin.isTTY; },
9
10
  namespace: () => input({ message: "Lakeshore namespace (on the queue server):" }),
@@ -251,6 +252,68 @@ export async function runQueuesWorkerClaims(prefix, workerId, opts) {
251
252
  return error(err);
252
253
  }
253
254
  }
255
+ // Shows or sets one owned worker's queue pin. While pinned, the worker claims
256
+ // queued jobs only from the pinned queues: its poll queue, membership and pool
257
+ // siblings are ignored. Set and clear go through DreamLake with the caller's
258
+ // ownership of the worker's host; the control-plane token stays server-side.
259
+ // Rollback order: disable claims and confirm, then clear the pin.
260
+ export async function runQueuesWorkerPin(prefix, workerId, opts, deps = {}) {
261
+ try {
262
+ const queues = opts.queue ?? [];
263
+ if (opts.clear && queues.length)
264
+ throw new Error("choose one of --queue or --clear");
265
+ if (!/^[a-f0-9]{24}$/.test(workerId))
266
+ throw new Error("worker ID must be the 24-character ID shown by 'dreamlake queues workers'");
267
+ const c = await context(opts);
268
+ const path = `${c.path}/${seg(prefix)}`;
269
+ const mount = await requestJson(c.remote, path, { token: c.token });
270
+ if (queues.length || opts.clear) {
271
+ if (!opts.host)
272
+ throw new Error("--host <namespace/group/host> is required to change a pin: you must own the worker's host");
273
+ const target = await (deps.resolve ?? resolveTarget)(opts.host, opts.enrollment);
274
+ if (target.workerId !== workerId || target.lakeshoreId !== mount.id)
275
+ throw new Error(`${opts.host} is not bound to worker ${workerId} on ${prefix}`);
276
+ await requestJson(c.remote, `${c.path}/${seg(mount.id)}/workers/${seg(workerId)}/queue-pin`, {
277
+ token: c.token, method: "POST",
278
+ json: { hostId: target.hostId, enrollmentId: target.enrollmentId, queues: opts.clear ? null : queues }
279
+ });
280
+ }
281
+ // Report what the control plane stores, not what was requested.
282
+ const view = await requestJson(c.remote, `${path}/proxy/v1/namespaces/${seg(mount.lakeshoreNs)}/workers/${seg(workerId)}`, { token: c.token });
283
+ if (!Object.hasOwn(view, "queuePin"))
284
+ throw new Error("this Lakeshore control plane does not report queuePin; it predates the worker queue pin");
285
+ const result = { workerId: view.id ?? workerId, label: view.label ?? null, state: view.state ?? null,
286
+ queuePin: view.queuePin ?? null, claimJobs: view.claimJobs ?? null };
287
+ if (opts.json)
288
+ emitJson(result);
289
+ else
290
+ process.stdout.write(`${result.label ?? result.workerId}: ` + (Array.isArray(result.queuePin)
291
+ ? `pinned to ${result.queuePin.join(", ")} (no other queue is claimed)` : "not pinned") + "\n");
292
+ return 0;
293
+ }
294
+ catch (err) {
295
+ return error(err);
296
+ }
297
+ }
298
+ // Creates one queue with control-plane defaults (fifo, active, no pool).
299
+ export async function runQueuesCreate(prefix, name, opts) {
300
+ try {
301
+ if (!/^[a-z0-9][a-z0-9-]*$/.test(name) || name === "default")
302
+ throw new Error("queue name must match ^[a-z0-9][a-z0-9-]*$ and not be default");
303
+ const c = await context(opts);
304
+ const path = `${c.path}/${seg(prefix)}`;
305
+ const mount = await requestJson(c.remote, path, { token: c.token });
306
+ const created = await requestJson(c.remote, `${path}/proxy/v1/namespaces/${seg(mount.lakeshoreNs)}/queues`, { token: c.token, method: "POST", json: { name } });
307
+ if (opts.json)
308
+ emitJson(created);
309
+ else
310
+ process.stdout.write(`created queue ${created.name ?? name} (${created.state ?? "active"})\n`);
311
+ return 0;
312
+ }
313
+ catch (err) {
314
+ return error(err);
315
+ }
316
+ }
254
317
  export function registerQueuesCommand(program) {
255
318
  const queues = program.command("queues").description("mount Lakeshore servers and view live queues through DreamLake");
256
319
  registerSlurmCommands(queues);
@@ -277,6 +340,14 @@ export function registerQueuesCommand(program) {
277
340
  .option("--disable", "stop claiming new jobs from every queue")
278
341
  .option("--enable", "resume claiming jobs"))
279
342
  .action(async (prefix, workerId, opts) => { process.exitCode = await runQueuesWorkerClaims(prefix, workerId, opts); });
343
+ common(queues.command("worker-pin <prefix> <worker-id>").description("show or set which queues one owned worker claims from; nothing else is claimed while pinned")
344
+ .option("--queue <name>", "pin to this queue (repeatable, up to 4)", (v, prev = []) => [...prev, v])
345
+ .option("--clear", "remove the pin (disable the worker's job claims first)")
346
+ .option("--host <selector>", "namespace/group/host you own, bound to this worker (required to change the pin)")
347
+ .option("--enrollment <id>", "the host enrollment, when it has more than one"))
348
+ .action(async (prefix, workerId, opts) => { process.exitCode = await runQueuesWorkerPin(prefix, workerId, opts); });
349
+ common(queues.command("create <prefix> <name>").description("create one queue on a mounted server (fifo, active, no pool)"))
350
+ .action(async (prefix, name, opts) => { process.exitCode = await runQueuesCreate(prefix, name, opts); });
280
351
  common(queues.command("jobs <prefix>").description("view jobs on a mounted server").option("--limit <count>", "maximum jobs").option("--offset <count>", "pagination offset"))
281
352
  .action(async (prefix, opts) => { process.exitCode = await runQueuesResources(prefix, "jobs", opts); });
282
353
  common(collectionList(queues, "list <prefix>").description("list live queues on a mounted server"))
@@ -0,0 +1,73 @@
1
+ import { hostStatus } from "../hosts/enroll.js";
2
+ import { type BridgeDeps } from "../python.js";
3
+ export declare const TASK_PROTOCOL_V2 = "dreamlake-bound-task-v2";
4
+ /** Mirrors the server's caps: the archive travels inline in the submission. */
5
+ export declare const INLINE_ARCHIVE_MAX: number;
6
+ export declare const INLINE_INPUT_MAX: number;
7
+ export interface Target {
8
+ namespace: string;
9
+ hostId: string;
10
+ enrollmentId: string;
11
+ workerId: string;
12
+ lakeshoreId: string;
13
+ lakeshoreSlug: string;
14
+ lakeshoreNs: string;
15
+ worker: Record<string, any>;
16
+ }
17
+ /** Host selector → owned Host, its one (or the selected) enrollment, its connection and the CP worker bound to it. */
18
+ export declare function resolveTarget(selector: string, enrollment?: string, deps?: {
19
+ status?: typeof hostStatus;
20
+ }): Promise<Target>;
21
+ export declare function buildTaskRequestV2(digest: string, o: {
22
+ queue: string;
23
+ target: {
24
+ hostId: string;
25
+ enrollmentId: string;
26
+ workerId: string;
27
+ };
28
+ inputs: unknown;
29
+ timeoutSeconds: number;
30
+ attempt: number;
31
+ }): {
32
+ protocol: string;
33
+ executionDigest: string;
34
+ queue: string;
35
+ target: {
36
+ hostId: string;
37
+ enrollmentId: string;
38
+ workerId: string;
39
+ };
40
+ timeoutSeconds: number;
41
+ inputs: Record<string, any>;
42
+ attempt: number;
43
+ taskKey: string;
44
+ invocationId: string;
45
+ };
46
+ export interface TargetBindOptions {
47
+ target: string;
48
+ enrollment?: string;
49
+ project: string;
50
+ sourcePath?: string;
51
+ python?: string;
52
+ config?: string;
53
+ dryRun?: boolean;
54
+ json?: boolean;
55
+ }
56
+ export declare function runBindViaDreamLake(ref: string, opts: TargetBindOptions, deps?: BridgeDeps & {
57
+ status?: typeof hostStatus;
58
+ }): Promise<number>;
59
+ export interface TargetExecuteOptions {
60
+ target: string;
61
+ enrollment?: string;
62
+ queue?: string;
63
+ inputs?: string;
64
+ attempt?: string;
65
+ timeoutSeconds?: string;
66
+ waitSeconds?: string;
67
+ wait?: boolean;
68
+ json?: boolean;
69
+ }
70
+ export declare function runTargetedCommand(command: "execute" | "receipt", ref: string, opts: TargetExecuteOptions, deps?: {
71
+ status?: typeof hostStatus;
72
+ sleep?: (ms: number) => Promise<void>;
73
+ }): Promise<number>;
@@ -0,0 +1,211 @@
1
+ // DreamLake-mediated bound executions (`--target <namespace/group/host>`).
2
+ //
3
+ // Unlike the `--server` path, no control-plane credential is used here: the
4
+ // DreamLake server holds the target enrollment's connection, uploads the small
5
+ // configured archive, submits to the target worker's pinned queue with the
6
+ // archive inline, and reads the receipt. The caller must own the target host.
7
+ // The task request is v2: its `target` {hostId, enrollmentId, workerId} is part
8
+ // of the task key and invocation ID, so retargeting is a different task.
9
+ import { createHash } from "node:crypto";
10
+ import { mkdtempSync, readFileSync, rmSync } from "node:fs";
11
+ import { tmpdir } from "node:os";
12
+ import { join } from "node:path";
13
+ import { requestJson } from "../client.js";
14
+ import { resolveRemote, resolveToken } from "../config.js";
15
+ import { emitJson, fail, ok } from "../helpers.js";
16
+ import { hostStatus } from "../hosts/enroll.js";
17
+ import { callBridge } from "../python.js";
18
+ import { canonical, checkRegisteredVersion, readBinding, sha256, executionReference, buildBinding } from "./bound.js";
19
+ import { pinnedReference } from "./run.js";
20
+ export const TASK_PROTOCOL_V2 = "dreamlake-bound-task-v2";
21
+ /** Mirrors the server's caps: the archive travels inline in the submission. */
22
+ export const INLINE_ARCHIVE_MAX = 128 * 1024;
23
+ export const INLINE_INPUT_MAX = 16 * 1024;
24
+ const OID = /^[a-f0-9]{24}$/;
25
+ const QUEUE = /^[a-z0-9][a-z0-9-]{0,62}$/;
26
+ const VERSION = /^\d+\.\d+\.\d+$/;
27
+ const seg = encodeURIComponent;
28
+ const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
29
+ function session() {
30
+ const token = resolveToken();
31
+ if (!token)
32
+ throw new Error("Log in to DreamLake first");
33
+ return { remote: resolveRemote(), token };
34
+ }
35
+ /** Host selector → owned Host, its one (or the selected) enrollment, its connection and the CP worker bound to it. */
36
+ export async function resolveTarget(selector, enrollment, deps = {}) {
37
+ const parts = selector.split("/");
38
+ if (parts.length !== 3 || selector.includes("*"))
39
+ throw new Error("--target must be one host: namespace/group/host");
40
+ const detail = await (deps.status ?? hostStatus)(selector, {});
41
+ const hostId = String(detail?.host?.id ?? "");
42
+ const rows = (detail?.enrollments ?? []).filter((e) => !enrollment || e.id === enrollment);
43
+ if (!OID.test(hostId) || rows.length !== 1 || !OID.test(rows[0].id) || !OID.test(rows[0].lakeshoreId ?? ""))
44
+ throw new Error(enrollment ? `Enrollment ${enrollment} is not on ${selector}` : `${selector} has ${rows.length} enrollments; pass --enrollment`);
45
+ const { remote, token } = session();
46
+ const namespace = parts[0];
47
+ const mounts = await requestJson(remote, `/namespaces/${seg(namespace)}/lakeshores`, { token, query: { pageSize: "200" } });
48
+ const mount = (mounts?.lakeshores ?? []).find((m) => m.id === rows[0].lakeshoreId);
49
+ if (!mount?.slug || !mount?.lakeshoreNs)
50
+ throw new Error(`The connection of ${selector} is not visible in ${namespace}`);
51
+ const workers = await requestJson(remote, `/namespaces/${seg(namespace)}/lakeshores/${seg(mount.slug)}/proxy/v1/namespaces/${seg(mount.lakeshoreNs)}/workers`, { token });
52
+ const matching = (Array.isArray(workers) ? workers : []).filter(w => w?.enrollmentId === rows[0].id && w?.hostId === hostId);
53
+ if (matching.length !== 1 || !OID.test(matching[0].id))
54
+ throw new Error(`No single control-plane worker is bound to ${selector}`);
55
+ return { namespace, hostId, enrollmentId: rows[0].id, workerId: matching[0].id, lakeshoreId: mount.id,
56
+ lakeshoreSlug: mount.slug, lakeshoreNs: mount.lakeshoreNs, worker: matching[0] };
57
+ }
58
+ export function buildTaskRequestV2(digest, o) {
59
+ if (!QUEUE.test(o.queue) || o.queue === "default")
60
+ throw new Error("--queue must be the target's dedicated (pinned) queue");
61
+ if (!Number.isInteger(o.timeoutSeconds) || o.timeoutSeconds < 1 || o.timeoutSeconds > 86400)
62
+ throw new Error("--timeout-seconds must be 1..86400");
63
+ if (!Number.isInteger(o.attempt) || o.attempt < 1 || o.attempt > 1000)
64
+ throw new Error("--attempt must be 1..1000");
65
+ if (!object(o.inputs))
66
+ throw new Error("--inputs must hold one JSON object");
67
+ if (Buffer.byteLength(canonical(o.inputs)) > INLINE_INPUT_MAX)
68
+ throw new Error(`Inputs exceed ${INLINE_INPUT_MAX} bytes`);
69
+ const target = { hostId: o.target.hostId, enrollmentId: o.target.enrollmentId, workerId: o.target.workerId };
70
+ const taskKey = sha256(canonical({ protocol: TASK_PROTOCOL_V2, executionDigest: digest, queue: o.queue, target,
71
+ timeoutSeconds: o.timeoutSeconds, inputs: o.inputs }));
72
+ return { protocol: TASK_PROTOCOL_V2, executionDigest: digest, queue: o.queue, target, timeoutSeconds: o.timeoutSeconds,
73
+ inputs: o.inputs, attempt: o.attempt, taskKey, invocationId: `bx1-${taskKey.slice(0, 40)}-a${o.attempt}` };
74
+ }
75
+ export async function runBindViaDreamLake(ref, opts, deps = {}) {
76
+ const dir = mkdtempSync(join(tmpdir(), "dreamlake-bind-"));
77
+ try {
78
+ const pin = pinnedReference(ref);
79
+ const { remote, token } = session();
80
+ const base = `/namespaces/${seg(pin.namespace)}`;
81
+ const get = (path) => requestJson(remote, path, { token, redirect: "error" });
82
+ const head = await get(`${base}/runnables/${seg(pin.name)}`);
83
+ const version = await get(`${base}/runnables/${seg(pin.name)}/versions/${pin.version}`);
84
+ if (!object(version?.metadata) || !OID.test(version.metadata.repo_id))
85
+ throw new Error("Version has no version-owned repository binding; register it with a .dreamrc repo first");
86
+ const repo = await get(`${base}/repos/${version.metadata.repo_id}`);
87
+ const { meta } = checkRegisteredVersion(ref, head, version, repo);
88
+ const project = opts.project.replace(/\/+$/, "") || ".";
89
+ const sourcePath = opts.sourcePath ?? (project === "." ? meta.source_file : `${project}/${meta.source_file}`);
90
+ const target = await resolveTarget(opts.target, opts.enrollment, deps);
91
+ if (target.namespace !== pin.namespace)
92
+ throw new Error(`--target must be in namespace ${pin.namespace}`);
93
+ // The exact archive bytes, built locally by the SDK; the server re-checks them.
94
+ const file = join(dir, "archive.tar.gz");
95
+ const built = callBridge("build-snapshot", ["--out", file, ...(opts.config ? ["--config", opts.config] : [])], { ...deps, quiet: opts.json ?? deps.quiet });
96
+ if (!built.ok)
97
+ throw new Error(built.message);
98
+ const described = callBridge("describe-archive", ["--file", file, "--project", project, "--source-path", sourcePath], { ...deps, quiet: true });
99
+ if (!described.ok)
100
+ throw new Error(described.message);
101
+ const d = described.data;
102
+ const bytes = readFileSync(file);
103
+ if (bytes.length > INLINE_ARCHIVE_MAX)
104
+ throw new Error(`The configured archive is ${bytes.length} bytes; DreamLake-submitted executions take at most ${INLINE_ARCHIVE_MAX}`);
105
+ const actual = createHash("sha256").update(bytes).digest("hex");
106
+ if (actual !== d.archive?.sha256 || actual !== built.data?.sha256)
107
+ throw new Error("The built archive changed while describing it");
108
+ if (d.files?.[sourcePath] !== pin.version)
109
+ throw new Error(`${sourcePath} in the archive is not the registered source ${pin.version}`);
110
+ const pythonVersion = opts.python ?? d.pythonVersion;
111
+ if (typeof pythonVersion !== "string" || !VERSION.test(pythonVersion))
112
+ throw new Error("The runtime needs an exact X.Y.Z Python version: commit it in <project>/.python-version or pass --python");
113
+ if (d.pythonVersion && d.pythonVersion !== pythonVersion)
114
+ throw new Error(`--python ${pythonVersion} disagrees with .python-version ${d.pythonVersion}`);
115
+ if (opts.dryRun) {
116
+ emitJson({ status: "dry-run", archive: d.archive, target: { hostId: target.hostId, enrollmentId: target.enrollmentId } });
117
+ return 0;
118
+ }
119
+ const up = await requestJson(remote, `${base}/repos/${seg(repo.id)}/configured-snapshots`, { method: "POST", token, json: {
120
+ lakeshoreId: target.lakeshoreId, hostId: target.hostId, enrollmentId: target.enrollmentId,
121
+ sha256: d.archive.sha256, archive: bytes.toString("base64")
122
+ } });
123
+ if (up?.archive?.sha256 !== d.archive.sha256 || !OID.test(up?.repoSnapshot?.id ?? "") || !OID.test(up?.controlPlane?.codeRepoId ?? ""))
124
+ throw new Error("Unexpected configured-snapshot receipt; inspect before retrying");
125
+ for (const rel of [sourcePath, `${project}/uv.lock`, `${project}/pyproject.toml`].map(p => p.replace(/^\.\//, "")))
126
+ if (up.files?.[rel] !== d.files?.[rel] && d.files?.[rel] !== undefined)
127
+ throw new Error(`Server and local digests differ for ${rel}`);
128
+ const cp = up.controlPlane;
129
+ const binding = buildBinding({ head, version, repo, snapshotRow: up.repoSnapshot, sourcePath, project, pythonVersion,
130
+ described: { origin: cp.origin, namespace: cp.namespace, archive: d.archive, files: d.files,
131
+ codeRepo: { id: cp.codeRepoId, commit: cp.commit, archiveKey: cp.archiveKey, storageName: cp.storageName } } });
132
+ const text = canonical(binding);
133
+ const digest = sha256(text);
134
+ const stored = await requestJson(remote, `${base}/runnables/${seg(head.id)}/executions`, { method: "POST", token, json: { binding, executionDigest: digest } });
135
+ if (stored?.executionDigest !== digest || stored?.canonical !== text)
136
+ throw new Error("Unexpected execution-binding receipt; inspect before retrying");
137
+ const execRef = `exec/${pin.namespace}/${pin.name}@${digest}`;
138
+ if (opts.json)
139
+ emitJson({ status: "bound", ref: execRef, executionDigest: digest, binding });
140
+ else {
141
+ ok(`bound ${execRef}`);
142
+ process.stdout.write(` archive: ${binding.archive.sha256} (${bytes.length} bytes, uploaded through DreamLake)\n` +
143
+ ` CodeRepo: ${cp.codeRepoId} (${cp.origin} ${cp.namespace})\n runtime: CPython ${pythonVersion}, uv.lock ${binding.runtime.lockSha256}\n`);
144
+ }
145
+ return 0;
146
+ }
147
+ catch (e) {
148
+ fail(e.message);
149
+ return 1;
150
+ }
151
+ finally {
152
+ rmSync(dir, { recursive: true, force: true });
153
+ }
154
+ }
155
+ const TERMINAL = new Set(["succeeded", "failed", "cancelled", "timed_out"]);
156
+ export async function runTargetedCommand(command, ref, opts, deps = {}) {
157
+ let request;
158
+ try {
159
+ const { binding } = await readBinding(ref);
160
+ const { digest, namespace } = executionReference(ref);
161
+ const target = await resolveTarget(opts.target, opts.enrollment, deps);
162
+ if (target.namespace !== namespace)
163
+ throw new Error(`--target must be in namespace ${namespace}`);
164
+ if (binding.controlPlane?.namespace !== target.lakeshoreNs)
165
+ throw new Error("The binding names another control plane than the target's connection");
166
+ if (!opts.queue || !opts.inputs)
167
+ throw new Error("--queue and --inputs are required");
168
+ request = buildTaskRequestV2(digest, { queue: opts.queue, target, inputs: JSON.parse(readFileSync(opts.inputs, "utf8")),
169
+ timeoutSeconds: Number(opts.timeoutSeconds ?? 3600), attempt: Number(opts.attempt ?? 1) });
170
+ process.stderr.write(`Invocation: ${request.invocationId}\nTask key: ${request.taskKey}\nAttempt: ${request.attempt}\n`);
171
+ const { remote, token } = session();
172
+ const base = `/namespaces/${seg(namespace)}/runnables/${seg(binding.udf.runnableId)}/executions/${digest}/attempts`;
173
+ if (command === "execute") {
174
+ const sent = await requestJson(remote, base, { method: "POST", token, json: { request } });
175
+ if (sent?.invocationId !== request.invocationId || sent?.taskKey !== request.taskKey)
176
+ throw new Error("Submission receipt does not belong to this request");
177
+ }
178
+ const wait = command === "receipt" ? Number(opts.waitSeconds ?? 0) : opts.wait === false ? 0 : Number(opts.waitSeconds ?? request.timeoutSeconds + 60);
179
+ const deadline = Date.now() + wait * 1000;
180
+ let view;
181
+ for (;;) {
182
+ view = await requestJson(remote, `${base}/${seg(request.invocationId)}`, { token,
183
+ query: { hostId: target.hostId, enrollmentId: target.enrollmentId } });
184
+ if (TERMINAL.has(view?.state) || Date.now() >= deadline)
185
+ break;
186
+ await (deps.sleep ?? (ms => new Promise(r => setTimeout(r, ms))))(2000);
187
+ }
188
+ if (view?.invocationId !== request.invocationId || view?.taskKey !== request.taskKey)
189
+ throw new Error("Receipt does not belong to this request");
190
+ const receipt = object(view.receipt) ? view.receipt : null;
191
+ if (receipt && (receipt.invocationId !== request.invocationId || receipt.taskKey !== request.taskKey || receipt.executionDigest !== digest))
192
+ throw new Error("Stored receipt does not belong to this attempt");
193
+ const status = receipt ? String(receipt.status) : command === "execute" && opts.wait === false ? "submitted" : String(view.state ?? "pending");
194
+ const record = { status, ref, invocationId: request.invocationId, taskKey: request.taskKey, attempt: request.attempt,
195
+ executionDigest: digest, queue: request.queue, target: request.target, workerId: view.workerId ?? null, state: view.state, receipt };
196
+ if (opts.json)
197
+ emitJson(record);
198
+ else {
199
+ ok(`${status} ${request.invocationId}`);
200
+ if (receipt)
201
+ process.stdout.write(JSON.stringify(receipt, null, 2) + "\n");
202
+ else if (!TERMINAL.has(view.state))
203
+ process.stdout.write(" still running; repeat the same command to recover — do not change --attempt\n");
204
+ }
205
+ return status === "succeeded" || status === "submitted" ? 0 : 1;
206
+ }
207
+ catch (e) {
208
+ fail(`${e.message}` + (request ? `\nInvocation: ${request.invocationId}; repeat the same command and inputs to recover` : ""));
209
+ return 1;
210
+ }
211
+ }
@@ -0,0 +1,88 @@
1
+ import type { Command } from "commander";
2
+ import { type BridgeDeps } from "../python.js";
3
+ export declare const BINDING_PROTOCOL = "dreamlake-execution-binding-v1";
4
+ export declare const RUNNER_PROTOCOL = "dreamlake-bound-udf-v1";
5
+ export declare const TASK_PROTOCOL = "dreamlake-bound-task-v1";
6
+ export declare const RUNTIME_ENVIRONMENT = "uv-sync-locked-v1";
7
+ export declare const sha256: (text: string) => string;
8
+ /** Same bytes as Python json.dumps(sort_keys=True, separators=(",", ":"), ensure_ascii=True). */
9
+ export declare function canonical(value: unknown, depth?: number): string;
10
+ /** First dreamlake-lakeshore release with the bound bridge commands. */
11
+ export declare const MIN_BOUND_SDK = "0.5.1";
12
+ /** WHATWG origin, the spelling the SDK bridge compares against. */
13
+ export declare function originOf(server: string): string;
14
+ export declare function executionReference(ref: string): {
15
+ namespace: string;
16
+ name: string;
17
+ digest: string;
18
+ };
19
+ export interface BindOptions {
20
+ snapshot: string;
21
+ server?: string;
22
+ cpNamespace?: string;
23
+ project: string;
24
+ sourcePath?: string;
25
+ python?: string;
26
+ dryRun?: boolean;
27
+ json?: boolean;
28
+ }
29
+ /** Registry reads + checks that need no archive. Mirrors server-side rules. */
30
+ export declare function checkRegisteredVersion(ref: string, head: any, version: any, repo: any): {
31
+ pin: {
32
+ namespace: string;
33
+ name: string;
34
+ version: string;
35
+ };
36
+ meta: Record<string, any>;
37
+ };
38
+ export declare function buildBinding(args: {
39
+ head: any;
40
+ version: any;
41
+ repo: any;
42
+ snapshotRow: any;
43
+ described: Record<string, any>;
44
+ sourcePath: string;
45
+ project: string;
46
+ pythonVersion: string;
47
+ }): Record<string, any>;
48
+ export declare function runBind(ref: string, opts: BindOptions, deps?: BridgeDeps): Promise<number>;
49
+ export interface ExecuteOptions {
50
+ queue?: string;
51
+ inputs?: string;
52
+ attempt?: string;
53
+ invocationId?: string;
54
+ timeoutSeconds?: string;
55
+ waitSeconds?: string;
56
+ server?: string;
57
+ cpNamespace?: string;
58
+ wait?: boolean;
59
+ json?: boolean;
60
+ }
61
+ export declare function buildTaskRequest(digest: string, o: {
62
+ queue: string;
63
+ inputs: unknown;
64
+ timeoutSeconds: number;
65
+ attempt: number;
66
+ invocationId?: string;
67
+ }): {
68
+ protocol: string;
69
+ executionDigest: string;
70
+ queue: string;
71
+ timeoutSeconds: number;
72
+ inputs: Record<string, any>;
73
+ attempt: number;
74
+ taskKey: string;
75
+ invocationId: string;
76
+ };
77
+ /** Read the immutable binding and prove it is the digest the ref names. */
78
+ export declare function readBinding(ref: string): Promise<{
79
+ ref: {
80
+ namespace: string;
81
+ name: string;
82
+ digest: string;
83
+ };
84
+ binding: any;
85
+ text: string;
86
+ }>;
87
+ export declare function runBoundCommand(command: "launch-bound" | "bound-receipt", ref: string, opts: ExecuteOptions, deps?: BridgeDeps): Promise<number>;
88
+ export declare function registerRunnableBound(runnable: Command): void;