@relayflows/sdk 2.0.31 → 2.0.33

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.
Files changed (95) hide show
  1. package/dist/authored-preflight.d.ts +4 -0
  2. package/dist/authored-preflight.d.ts.map +1 -0
  3. package/dist/authored-preflight.js +50 -0
  4. package/dist/authored-preflight.js.map +1 -0
  5. package/dist/authored-worker-step.d.ts.map +1 -1
  6. package/dist/authored-worker-step.js +3 -2
  7. package/dist/authored-worker-step.js.map +1 -1
  8. package/dist/cli/check.d.ts +10 -2
  9. package/dist/cli/check.d.ts.map +1 -1
  10. package/dist/cli/check.js +16 -137
  11. package/dist/cli/check.js.map +1 -1
  12. package/dist/cli/cli-probe.d.ts +20 -0
  13. package/dist/cli/cli-probe.d.ts.map +1 -0
  14. package/dist/cli/cli-probe.js +166 -0
  15. package/dist/cli/cli-probe.js.map +1 -0
  16. package/dist/cli/cloud-mirror-session.d.ts +97 -0
  17. package/dist/cli/cloud-mirror-session.d.ts.map +1 -0
  18. package/dist/cli/cloud-mirror-session.js +264 -0
  19. package/dist/cli/cloud-mirror-session.js.map +1 -0
  20. package/dist/cli-commands.d.ts +6 -0
  21. package/dist/cli-commands.d.ts.map +1 -1
  22. package/dist/cli-commands.js +1 -0
  23. package/dist/cli-commands.js.map +1 -1
  24. package/dist/cli.d.ts +7 -0
  25. package/dist/cli.d.ts.map +1 -1
  26. package/dist/cli.js +84 -18
  27. package/dist/cli.js.map +1 -1
  28. package/dist/cloud-deploy.d.ts +1 -1
  29. package/dist/cloud-deploy.d.ts.map +1 -1
  30. package/dist/cloud-deploy.js +24 -8
  31. package/dist/cloud-deploy.js.map +1 -1
  32. package/dist/cloud-mirror-ledger.d.ts +40 -0
  33. package/dist/cloud-mirror-ledger.d.ts.map +1 -0
  34. package/dist/cloud-mirror-ledger.js +142 -0
  35. package/dist/cloud-mirror-ledger.js.map +1 -0
  36. package/dist/cloud-mirror-step.d.ts +180 -0
  37. package/dist/cloud-mirror-step.d.ts.map +1 -0
  38. package/dist/cloud-mirror-step.js +523 -0
  39. package/dist/cloud-mirror-step.js.map +1 -0
  40. package/dist/cloud-mirror-transport.d.ts +94 -0
  41. package/dist/cloud-mirror-transport.d.ts.map +1 -0
  42. package/dist/cloud-mirror-transport.js +163 -0
  43. package/dist/cloud-mirror-transport.js.map +1 -0
  44. package/dist/cloud-mirror.d.ts +132 -0
  45. package/dist/cloud-mirror.d.ts.map +1 -0
  46. package/dist/cloud-mirror.js +556 -0
  47. package/dist/cloud-mirror.js.map +1 -0
  48. package/dist/cloud-transcript-codex.d.ts.map +1 -1
  49. package/dist/cloud-transcript-codex.js +90 -4
  50. package/dist/cloud-transcript-codex.js.map +1 -1
  51. package/dist/cloud-transcript-types.d.ts +19 -1
  52. package/dist/cloud-transcript-types.d.ts.map +1 -1
  53. package/dist/cloud-transcript-types.js.map +1 -1
  54. package/dist/cloud-transcript.d.ts +1 -1
  55. package/dist/cloud-transcript.d.ts.map +1 -1
  56. package/dist/cloud-transcript.js +10 -0
  57. package/dist/cloud-transcript.js.map +1 -1
  58. package/dist/helper-reference.d.ts.map +1 -1
  59. package/dist/helper-reference.js +134 -6
  60. package/dist/helper-reference.js.map +1 -1
  61. package/dist/hosted-extension-runtime.js +1 -1
  62. package/dist/hosted-extension-sandbox.js +1 -1
  63. package/dist/package-version.d.ts +10 -0
  64. package/dist/package-version.d.ts.map +1 -0
  65. package/dist/package-version.js +22 -0
  66. package/dist/package-version.js.map +1 -0
  67. package/dist/preflight.d.ts +14 -0
  68. package/dist/preflight.d.ts.map +1 -1
  69. package/dist/preflight.js +18 -3
  70. package/dist/preflight.js.map +1 -1
  71. package/dist/relay-cli.d.ts.map +1 -1
  72. package/dist/relay-cli.js +1 -21
  73. package/dist/relay-cli.js.map +1 -1
  74. package/package.json +2 -2
  75. package/src/authored-preflight.ts +46 -0
  76. package/src/authored-worker-step.ts +4 -3
  77. package/src/cli/check.ts +25 -163
  78. package/src/cli/cli-probe.ts +194 -0
  79. package/src/cli/cloud-mirror-session.ts +329 -0
  80. package/src/cli-commands.ts +1 -0
  81. package/src/cli.ts +94 -19
  82. package/src/cloud-deploy.ts +26 -8
  83. package/src/cloud-mirror-ledger.ts +161 -0
  84. package/src/cloud-mirror-step.ts +650 -0
  85. package/src/cloud-mirror-transport.ts +261 -0
  86. package/src/cloud-mirror.ts +633 -0
  87. package/src/cloud-transcript-codex.ts +96 -4
  88. package/src/cloud-transcript-types.ts +18 -1
  89. package/src/cloud-transcript.ts +9 -1
  90. package/src/helper-reference.ts +131 -6
  91. package/src/hosted-extension-runtime.ts +1 -1
  92. package/src/hosted-extension-sandbox.ts +1 -1
  93. package/src/package-version.ts +23 -0
  94. package/src/preflight.ts +31 -7
  95. package/src/relay-cli.ts +1 -24
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cloud-mirror-ledger.d.ts","sourceRoot":"","sources":["../src/cloud-mirror-ledger.ts"],"names":[],"mappings":"AAoCA,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAC7C;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAA4B,CAAC;AAC3D,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,MAAM,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7B"}
@@ -0,0 +1,142 @@
1
+ // Which Cloud run mirrored which journal, remembered between invocations.
2
+ //
3
+ // A journal outlives the process that started it: `flows run` parks on an
4
+ // `f.human`, exits, and some time later a different `flows resume` picks the
5
+ // same journal up. Cloud models that second attempt as its own run row — its
6
+ // own hosted resume mints a fresh run id too — so a parked-then-resumed flow
7
+ // is two rows however it is driven. What made that read as two *unrelated*
8
+ // pieces of work was that the resuming process had no idea the first attempt
9
+ // existed: nothing on disk connected the journal to the Cloud run mirroring
10
+ // it, so the second registration could not name its predecessor.
11
+ //
12
+ // This is that connection, and deliberately nothing more.
13
+ //
14
+ // ## What is stored, and what is not
15
+ //
16
+ // The run id and the deployment that issued it. **Never the credential.** The
17
+ // run token can write this run's steps and read the workspace's runs; leaving
18
+ // one in a dotfile under a developer's home directory, for every run they
19
+ // have ever started, would be a worse trade than the feature is worth. A
20
+ // resume mints its own credential the same way the first attempt did — the
21
+ // registration request it already makes.
22
+ //
23
+ // So an entry is not a capability. Everything in it is already in the URL the
24
+ // first attempt printed to the terminal.
25
+ //
26
+ // ## Failure is not an error
27
+ //
28
+ // Every operation here is best-effort and silent. A missing entry means the
29
+ // resumed run registers without naming a predecessor, which is exactly what
30
+ // happened before this file existed; an unreadable or corrupt one means the
31
+ // same. A mirror is an observer, and bookkeeping for an observer must never
32
+ // be able to fail a run.
33
+ import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
34
+ import { join, resolve } from 'node:path';
35
+ /** Where the ledger lives, beside the journals it describes. */
36
+ export const LEDGER_DIRECTORY = 'cloud-runs';
37
+ /**
38
+ * How long an entry is worth keeping.
39
+ *
40
+ * A resume of a two-week-old parked run is a real thing; a resume of a run
41
+ * from last quarter is not the case this serves, and a ledger that only grows
42
+ * is a directory nobody ever looks at filling up forever.
43
+ */
44
+ export const LEDGER_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
45
+ /** Entries kept. Past it, the oldest are dropped on the next write. */
46
+ export const LEDGER_MAX_ENTRIES = 500;
47
+ const JOURNAL_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
48
+ const CLOUD_RUN_ID = /^[A-Za-z0-9_-]{1,128}$/u;
49
+ function entryPath(dataDir, journalRunId) {
50
+ return join(resolve(dataDir), LEDGER_DIRECTORY, `${journalRunId}.json`);
51
+ }
52
+ /**
53
+ * Record that `journalRunId` is mirrored by `entry.cloudRunId`.
54
+ *
55
+ * Written with mode 0600 for the same reason the journals are private: it
56
+ * names runs in someone's workspace, and a shared machine should not publish
57
+ * that. It is not a secret — there is nothing here to steal — but it is
58
+ * nobody else's business either.
59
+ */
60
+ export async function recordMirroredRun(dataDir, journalRunId, entry) {
61
+ if (!JOURNAL_RUN_ID.test(journalRunId) || !CLOUD_RUN_ID.test(entry.cloudRunId))
62
+ return;
63
+ const directory = join(resolve(dataDir), LEDGER_DIRECTORY);
64
+ try {
65
+ await mkdir(directory, { recursive: true, mode: 0o700 });
66
+ await writeFile(entryPath(dataDir, journalRunId), JSON.stringify({ cloudRunId: entry.cloudRunId, apiUrl: entry.apiUrl }), { mode: 0o600 });
67
+ }
68
+ catch {
69
+ // A resume that cannot name its predecessor is the behaviour this file
70
+ // improves on, not a failure of the run.
71
+ return;
72
+ }
73
+ await prune(directory);
74
+ }
75
+ /**
76
+ * The Cloud run mirroring this journal, if one is recorded *for this
77
+ * deployment*.
78
+ *
79
+ * The deployment check is not bookkeeping. A developer who ran a flow against
80
+ * staging and resumes it against production must not have the resumed run
81
+ * claim to continue a run id that means something else there — or, worse,
82
+ * nothing at all, which Cloud would refuse and which would read as a bug in
83
+ * the resume rather than in the pairing.
84
+ */
85
+ export async function readMirroredRun(dataDir, journalRunId, apiUrl) {
86
+ if (!JOURNAL_RUN_ID.test(journalRunId))
87
+ return undefined;
88
+ let parsed;
89
+ try {
90
+ parsed = JSON.parse(await readFile(entryPath(dataDir, journalRunId), 'utf8'));
91
+ }
92
+ catch {
93
+ return undefined;
94
+ }
95
+ if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
96
+ return undefined;
97
+ const entry = parsed;
98
+ if (typeof entry['cloudRunId'] !== 'string' || !CLOUD_RUN_ID.test(entry['cloudRunId']))
99
+ return undefined;
100
+ if (entry['apiUrl'] !== apiUrl)
101
+ return undefined;
102
+ return entry['cloudRunId'];
103
+ }
104
+ /** Drop entries past their age, then past the count. Never throws. */
105
+ async function prune(directory) {
106
+ try {
107
+ const names = (await readdir(directory)).filter(name => name.endsWith('.json'));
108
+ if (names.length <= LEDGER_MAX_ENTRIES) {
109
+ // Still age out: a data dir that never reaches the count cap would
110
+ // otherwise keep its first entry forever.
111
+ await dropOlderThan(directory, names, Date.now() - LEDGER_MAX_AGE_MS);
112
+ return;
113
+ }
114
+ const ages = await Promise.all(names.map(async (name) => {
115
+ try {
116
+ return { name, at: (await stat(join(directory, name))).mtimeMs };
117
+ }
118
+ catch {
119
+ return { name, at: 0 };
120
+ }
121
+ }));
122
+ ages.sort((left, right) => right.at - left.at);
123
+ await Promise.all(ages.slice(LEDGER_MAX_ENTRIES).map(entry => unlink(join(directory, entry.name)).catch(() => undefined)));
124
+ await dropOlderThan(directory, ages.slice(0, LEDGER_MAX_ENTRIES).map(entry => entry.name), Date.now() - LEDGER_MAX_AGE_MS);
125
+ }
126
+ catch {
127
+ return;
128
+ }
129
+ }
130
+ async function dropOlderThan(directory, names, floor) {
131
+ await Promise.all(names.map(async (name) => {
132
+ try {
133
+ if ((await stat(join(directory, name))).mtimeMs < floor) {
134
+ await unlink(join(directory, name));
135
+ }
136
+ }
137
+ catch {
138
+ return;
139
+ }
140
+ }));
141
+ }
142
+ //# sourceMappingURL=cloud-mirror-ledger.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cloud-mirror-ledger.js","sourceRoot":"","sources":["../src/cloud-mirror-ledger.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,180 @@
1
+ import { type RunView } from './run-state.js';
2
+ import type { JournalEvent } from './journal-reader.js';
3
+ /** Steps one snapshot may carry; a longer run publishes its live tail. */
4
+ export declare const SNAPSHOT_MAX_STEPS = 64;
5
+ /** Serialized snapshot envelope cap, against the real UTF-8 byte count. */
6
+ export declare const SNAPSHOT_MAX_BYTES: number;
7
+ /** Artifact paths named per step; the rest are counted. */
8
+ export declare const SNAPSHOT_ARTIFACTS_MAX = 5;
9
+ export declare const SNAPSHOT_ARTIFACT_MAX_CHARS = 200;
10
+ /** `stepName`, `journalRunId`, `stepType`, `completionReason`, gate, model. */
11
+ export declare const IDENTIFIER_MAX_CHARS = 128;
12
+ /** Predecessors one live step lists. */
13
+ export declare const SNAPSHOT_DEPENDS_ON_MAX = 32;
14
+ /** Predecessors a final row lists. */
15
+ export declare const DEPENDS_ON_MAX_ENTRIES = 256;
16
+ /** The backing columns are PostgreSQL 32-bit integers. */
17
+ export declare const MAX_INT32 = 2147483647;
18
+ /** `workflow_steps.display_name`, in code points. */
19
+ export declare const LABEL_MAX_CHARS = 120;
20
+ /** `workflow_steps.output_summary`. */
21
+ export declare const OUTPUT_SUMMARY_MAX_CHARS = 1000;
22
+ /** `workflow_steps.error`. */
23
+ export declare const ERROR_MAX_CHARS = 1024;
24
+ /** Serialized `workflow_steps.detail`. */
25
+ export declare const DETAIL_MAX_BYTES: number;
26
+ /** Attempt rows kept on `detail.attempts`; older ones are counted, not listed. */
27
+ export declare const DETAIL_MAX_ATTEMPTS = 20;
28
+ /**
29
+ * The one completion reason the kernel uses for success. Cloud keys a step's
30
+ * status off exactly this value, so the live derivation and the final row
31
+ * agree about what "completed" means.
32
+ */
33
+ export declare const SUCCESS_COMPLETION_REASON = "success";
34
+ /** The authored root step spans the whole flow; its children carry the steps. */
35
+ export declare const AUTHORED_ROOT_STEP = "authored-root";
36
+ /** Live kernel states Cloud publishes. A step that has not begun has no honest rendering. */
37
+ export type SnapshotState = 'running' | 'backoff' | 'waiting' | 'needs_human' | 'done';
38
+ export interface SnapshotStep {
39
+ stepName: string;
40
+ /** Child runs may repeat a step id, so identity is the pair. */
41
+ journalRunId: string;
42
+ stepType: string;
43
+ state: SnapshotState;
44
+ attempt: number;
45
+ elapsedMs: number;
46
+ completionReason?: string;
47
+ gate?: {
48
+ name: string;
49
+ verdict: string;
50
+ };
51
+ model?: string;
52
+ turns?: number;
53
+ toolCalls?: number;
54
+ costUsd?: number;
55
+ artifactCount?: number;
56
+ artifacts?: string[];
57
+ label?: string;
58
+ dependsOn?: string[];
59
+ }
60
+ /** One row of the final report; the field names are `workflow_steps`'s own. */
61
+ export interface FinalStep {
62
+ stepName: string;
63
+ stepType: string;
64
+ agent: string;
65
+ preset: string;
66
+ cli: string;
67
+ sandboxId: string;
68
+ startTime: string;
69
+ endTime: string;
70
+ durationMs: number;
71
+ exitCode: number;
72
+ outputSummary: string;
73
+ status: 'completed' | 'failed';
74
+ completionReason: string;
75
+ retryCount: number;
76
+ model?: string;
77
+ tokensInput?: number;
78
+ tokensOutput?: number;
79
+ /**
80
+ * True when tokens were counted but nobody priced them.
81
+ *
82
+ * The kernel already records this (`run-state.ts`'s `Spend`), and
83
+ * `flows status` already prints `(unmetered)` from it. Without it on the
84
+ * wire, Cloud cannot tell a step that genuinely cost nothing — a
85
+ * deterministic `echo` — from one that spent real money against an unpriced
86
+ * model: both arrive as an absent `costUsd` and render blank. Codex is the
87
+ * everyday case, because it selects its own model and never reports it, so
88
+ * `MODEL_PRICING` has nothing to match (`model-pricing.ts` says so outright).
89
+ */
90
+ costUnmetered?: true;
91
+ costUsd?: number;
92
+ error?: string;
93
+ detail?: Record<string, unknown>;
94
+ detailTruncated?: true;
95
+ label?: string;
96
+ dependsOn?: string[];
97
+ }
98
+ /** One step's per-attempt transcript files, for the `<stepName>/agent.log` upload. */
99
+ export interface StepTranscriptRef {
100
+ stepName: string;
101
+ attempts: Array<{
102
+ attempt: number;
103
+ path: string;
104
+ }>;
105
+ }
106
+ /** What one journal contributes, keyed for the caller's cross-journal cache. */
107
+ export interface MirroredJournal {
108
+ runId: string;
109
+ status: RunView['status'];
110
+ terminal: boolean;
111
+ steps: SnapshotStep[];
112
+ finals: FinalStep[];
113
+ transcripts: StepTranscriptRef[];
114
+ /** Child journals this run admitted, from an authored root's step index. */
115
+ children: string[];
116
+ /** Authored graph hints by step id, from an authored root's step index. */
117
+ hints: Map<string, {
118
+ label?: string;
119
+ after?: string[];
120
+ }>;
121
+ }
122
+ /**
123
+ * Redact, then normalize, then clip — in that order. Clipping first could
124
+ * leave the head of a secret standing; normalizing first would let a
125
+ * multi-character replacement push the result back over the cap.
126
+ */
127
+ export declare function identifier(value: unknown, env: NodeJS.ProcessEnv, maxChars?: number): string | undefined;
128
+ /** Free text, redacted then bounded by code points. Empty becomes undefined. */
129
+ export declare function text(value: unknown, env: NodeJS.ProcessEnv, maxChars: number): string | undefined;
130
+ /**
131
+ * A step label as `workflow_steps.display_name` accepts it: control characters
132
+ * become spaces, whitespace runs collapse, the result is trimmed and clipped.
133
+ */
134
+ export declare function label(value: unknown, env: NodeJS.ProcessEnv): string | undefined;
135
+ /** Cloud's own vocabulary for a live step, derived rather than carried. */
136
+ export declare function snapshotStepStatus(step: Pick<SnapshotStep, 'state' | 'completionReason'>): 'running' | 'completed' | 'failed';
137
+ /**
138
+ * Fold one journal into everything the mirror can say about it.
139
+ *
140
+ * The authored root is deliberately not published as a step: it spans the
141
+ * whole flow, so a snapshot carrying it would show one node called
142
+ * `authored-root` sitting at 100% for the run's entire duration beside the
143
+ * steps that actually did the work. Its journal is still read, for the step
144
+ * index that names the child journals and their graph edges.
145
+ */
146
+ export declare function mirrorJournal(runId: string, events: readonly JournalEvent[], nowMs: number, env?: NodeJS.ProcessEnv): MirroredJournal;
147
+ /**
148
+ * Build a snapshot envelope that actually fits both bounds.
149
+ *
150
+ * The count cap applies unconditionally — 65 tiny steps are 65 steps. Only
151
+ * then does the byte cap bite: first the artifact *names* go (their count
152
+ * survives), then the `dependsOn` edges, then whole entries from the head of
153
+ * the display order, because the tail is the newest work and that is what a
154
+ * live view exists to show. A capped view announces itself as incomplete;
155
+ * silently showing fewer steps than ran is the one thing it must not do.
156
+ */
157
+ export declare function fitSnapshot(steps: readonly SnapshotStep[], envelope: {
158
+ sequence: number;
159
+ capturedAt: string;
160
+ alreadyOmitted?: number;
161
+ }): {
162
+ sequence: number;
163
+ capturedAt: string;
164
+ truncated?: true;
165
+ omittedStepCount?: number;
166
+ steps: SnapshotStep[];
167
+ };
168
+ /** Apply an authored root's graph hints to a step, bounded for the live view. */
169
+ export declare function withGraphHints<T extends {
170
+ stepName: string;
171
+ journalRunId?: string;
172
+ }>(step: T, hints: Map<string, {
173
+ label?: string;
174
+ after?: string[];
175
+ }>, journalRunId: string, maxDependsOn: number, knownSteps: ReadonlySet<string>): T & {
176
+ label?: string;
177
+ dependsOn?: string[];
178
+ };
179
+ export type { RunView };
180
+ //# sourceMappingURL=cloud-mirror-step.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cloud-mirror-step.d.ts","sourceRoot":"","sources":["../src/cloud-mirror-step.ts"],"names":[],"mappings":"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"}