@agimon-ai/po-workflow 0.0.0-alpha.0 → 0.0.0-alpha.2

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.
@@ -20,7 +20,6 @@ import { Readable } from "node:stream";
20
20
  import { doomApiCallerFrom } from "@agimon-ai/po-core/packageApi";
21
21
  import { Hono } from "hono";
22
22
  import { streamSSE } from "hono/streaming";
23
- import { apiResponse, defineApiRoutes } from "@agimon-ai/po-core/web";
24
23
  import { fileURLToPath } from "node:url";
25
24
  import os from "node:os";
26
25
  //#region src/constants/workflow.ts
@@ -1945,13 +1944,19 @@ const ARTIFACT_NAME_PARAM = ":name{.+}";
1945
1944
  * route follows the run's current step, which is one of a parallel group's.
1946
1945
  */
1947
1946
  const STEP_TARGET_PARAM = "step";
1948
- var apiRoutes_default = defineApiRoutes({
1947
+ const routes = {
1949
1948
  /**
1950
1949
  * The terminal, as server-sent events.
1951
1950
  *
1952
1951
  * `stream: true` gets a URL and no call method: the consumer is the browser's
1953
1952
  * own `EventSource`, and a relayed call would buffer a stream that never ends.
1954
1953
  */
1954
+ snapshot: {
1955
+ method: "GET",
1956
+ path: `${RUN}/screen`,
1957
+ query: [STEP_TARGET_PARAM],
1958
+ response: void 0
1959
+ },
1955
1960
  screen: {
1956
1961
  method: "GET",
1957
1962
  path: `${RUN}/screen/stream`,
@@ -1961,7 +1966,7 @@ var apiRoutes_default = defineApiRoutes({
1961
1966
  control: {
1962
1967
  method: "POST",
1963
1968
  path: `${RUN}/control`,
1964
- response: apiResponse()
1969
+ response: void 0
1965
1970
  },
1966
1971
  keys: {
1967
1972
  method: "POST",
@@ -1970,23 +1975,23 @@ var apiRoutes_default = defineApiRoutes({
1970
1975
  resize: {
1971
1976
  method: "POST",
1972
1977
  path: `${RUN}/resize`,
1973
- response: apiResponse()
1978
+ response: void 0
1974
1979
  },
1975
1980
  remove: {
1976
1981
  method: "DELETE",
1977
1982
  path: RUN,
1978
- response: apiResponse()
1983
+ response: void 0
1979
1984
  },
1980
1985
  stop: {
1981
1986
  method: "POST",
1982
1987
  path: `${RUN}/stop`,
1983
- response: apiResponse()
1988
+ response: void 0
1984
1989
  },
1985
1990
  /** Guidance for the agent session the running step is in, like steering a Team sub-agent. */
1986
1991
  steer: {
1987
1992
  method: "POST",
1988
1993
  path: `${RUN}/steer`,
1989
- response: apiResponse()
1994
+ response: void 0
1990
1995
  },
1991
1996
  /**
1992
1997
  * Launch a workflow into the mounting session's own runtime, which then owns
@@ -1995,27 +2000,27 @@ var apiRoutes_default = defineApiRoutes({
1995
2000
  launch: {
1996
2001
  method: "POST",
1997
2002
  path: "/launch",
1998
- response: apiResponse()
2003
+ response: void 0
1999
2004
  },
2000
2005
  openRunDirectory: {
2001
2006
  method: "POST",
2002
2007
  path: `${RUN}/open-directory`,
2003
- response: apiResponse()
2008
+ response: void 0
2004
2009
  },
2005
2010
  artifacts: {
2006
2011
  method: "GET",
2007
2012
  path: `${RUN}/artifacts`,
2008
2013
  query: ["directory"],
2009
- response: apiResponse()
2014
+ response: void 0
2010
2015
  },
2011
2016
  /** One artifact: its metadata and text, or its raw bytes under `raw=1`. */
2012
2017
  artifact: {
2013
2018
  method: "GET",
2014
2019
  path: `${RUN}/artifacts/${ARTIFACT_NAME_PARAM}`,
2015
2020
  query: ["raw", "download"],
2016
- response: apiResponse()
2021
+ response: void 0
2017
2022
  }
2018
- });
2023
+ };
2019
2024
  //#endregion
2020
2025
  //#region src/types/webWorkflowTerminal.ts
2021
2026
  /**
@@ -2045,6 +2050,8 @@ const STAGES = [
2045
2050
  ];
2046
2051
  /** Lines of screen the stream sends, which is a terminal's visible height plus room. */
2047
2052
  const SCREEN_LINES = 48;
2053
+ /** Bound finite snapshots, including a maliciously wide terminal row. */
2054
+ const MAX_SCREEN_LINE_CHARS = 4096;
2048
2055
  /** How often the stream re-reads; the service coalesces, so this is an upper bound. */
2049
2056
  const STREAM_TICK_MS = 500;
2050
2057
  /** How often a settled run is re-checked before the stream closes itself. */
@@ -2147,7 +2154,29 @@ function createWorkflowHubApi(options = {}) {
2147
2154
  } catch {}
2148
2155
  };
2149
2156
  const missing = (workspace, runKey) => ({ error: `No workflow run '${runKey}' in workspace '${workspace}'.` });
2150
- app.get(apiRoutes_default.screen.path, async (context) => {
2157
+ app.get(routes.snapshot.path, async (context) => {
2158
+ const workspace = context.req.param("workspace");
2159
+ const runKey = context.req.param("runKey");
2160
+ const record = await runOf(workspace, runKey);
2161
+ if (record === void 0) return context.json(missing(workspace, runKey), 404);
2162
+ const step = stepOf(context.req.query(STEP_TARGET_PARAM));
2163
+ const target = {
2164
+ record,
2165
+ ...step === void 0 ? {} : { step }
2166
+ };
2167
+ const capabilities = terminal.capabilities(target);
2168
+ const captured = capabilities.readable ? await terminal.screen(runIdentityOf(workspace, runKey, step), target, SCREEN_LINES) : [];
2169
+ const lines = captured.slice(-48).map((line) => line.slice(0, MAX_SCREEN_LINE_CHARS));
2170
+ const truncated = captured.length > SCREEN_LINES || captured.some((line) => line.length > MAX_SCREEN_LINE_CHARS);
2171
+ const snapshot = {
2172
+ lines,
2173
+ capabilities,
2174
+ ...record.stage === "running" ? {} : { ended: true },
2175
+ ...truncated ? { truncated: true } : {}
2176
+ };
2177
+ return context.json(snapshot);
2178
+ });
2179
+ app.get(routes.screen.path, async (context) => {
2151
2180
  const workspace = context.req.param("workspace");
2152
2181
  const runKey = context.req.param("runKey");
2153
2182
  const record = await runOf(workspace, runKey);
@@ -2188,7 +2217,7 @@ function createWorkflowHubApi(options = {}) {
2188
2217
  if (latest.stage !== "running") terminal.forgetRun(identity);
2189
2218
  });
2190
2219
  });
2191
- app.post(apiRoutes_default.control.path, async (context) => {
2220
+ app.post(routes.control.path, async (context) => {
2192
2221
  const workspace = context.req.param("workspace");
2193
2222
  const runKey = context.req.param("runKey");
2194
2223
  const record = await runOf(workspace, runKey);
@@ -2222,7 +2251,7 @@ function createWorkflowHubApi(options = {}) {
2222
2251
  };
2223
2252
  return context.json(held);
2224
2253
  });
2225
- app.post(apiRoutes_default.keys.path, async (context) => {
2254
+ app.post(routes.keys.path, async (context) => {
2226
2255
  const workspace = context.req.param("workspace");
2227
2256
  const runKey = context.req.param("runKey");
2228
2257
  const record = await runOf(workspace, runKey);
@@ -2240,7 +2269,7 @@ function createWorkflowHubApi(options = {}) {
2240
2269
  }
2241
2270
  return context.body(null, 204);
2242
2271
  });
2243
- app.post(apiRoutes_default.resize.path, async (context) => {
2272
+ app.post(routes.resize.path, async (context) => {
2244
2273
  const workspace = context.req.param("workspace");
2245
2274
  const runKey = context.req.param("runKey");
2246
2275
  const record = await runOf(workspace, runKey);
@@ -2259,7 +2288,7 @@ function createWorkflowHubApi(options = {}) {
2259
2288
  return context.json({ error: error instanceof Error ? error.message : String(error) }, 409);
2260
2289
  }
2261
2290
  });
2262
- app.post(apiRoutes_default.stop.path, async (context) => {
2291
+ app.post(routes.stop.path, async (context) => {
2263
2292
  const workspace = context.req.param("workspace");
2264
2293
  const runKey = context.req.param("runKey");
2265
2294
  const record = await runOf(workspace, runKey);
@@ -2272,7 +2301,7 @@ function createWorkflowHubApi(options = {}) {
2272
2301
  }
2273
2302
  return context.json({ requested: true });
2274
2303
  });
2275
- app.post(apiRoutes_default.steer.path, async (context) => {
2304
+ app.post(routes.steer.path, async (context) => {
2276
2305
  const workspace = context.req.param("workspace");
2277
2306
  const runKey = context.req.param("runKey");
2278
2307
  const record = await runOf(workspace, runKey);
@@ -2293,12 +2322,12 @@ function createWorkflowHubApi(options = {}) {
2293
2322
  }
2294
2323
  return context.json({ delivered: true });
2295
2324
  });
2296
- app.post(apiRoutes_default.launch.path, async (context) => {
2325
+ app.post(routes.launch.path, async (context) => {
2297
2326
  if (options.launch === void 0) return context.json({ error: "Launching needs the mount of a session with a workflow runtime." }, 409);
2298
2327
  const response = await options.launch(await jsonBody(context));
2299
2328
  return context.json(response);
2300
2329
  });
2301
- app.delete(apiRoutes_default.remove.path, async (context) => {
2330
+ app.delete(routes.remove.path, async (context) => {
2302
2331
  const workspace = context.req.param("workspace");
2303
2332
  const runKey = context.req.param("runKey");
2304
2333
  const record = await runOf(workspace, runKey);
@@ -2316,7 +2345,7 @@ function createWorkflowHubApi(options = {}) {
2316
2345
  }
2317
2346
  return context.json({ deleted: true });
2318
2347
  });
2319
- app.post(apiRoutes_default.openRunDirectory.path, async (context) => {
2348
+ app.post(routes.openRunDirectory.path, async (context) => {
2320
2349
  if (doomApiCallerFrom(context.req.raw.headers)?.locality !== "local") return context.json({ error: "Opening Finder is only available on the host." }, 403);
2321
2350
  const workspace = context.req.param("workspace");
2322
2351
  const runKey = context.req.param("runKey");
@@ -2341,7 +2370,7 @@ function createWorkflowHubApi(options = {}) {
2341
2370
  return context.json({ error: error instanceof Error ? error.message : String(error) }, 409);
2342
2371
  }
2343
2372
  });
2344
- app.get(apiRoutes_default.artifacts.path, async (context) => {
2373
+ app.get(routes.artifacts.path, async (context) => {
2345
2374
  const workspace = context.req.param("workspace");
2346
2375
  const runKey = context.req.param("runKey");
2347
2376
  const record = await runOf(workspace, runKey);
@@ -2360,7 +2389,7 @@ function createWorkflowHubApi(options = {}) {
2360
2389
  return context.json({ error: error instanceof Error ? error.message : String(error) }, 409);
2361
2390
  }
2362
2391
  });
2363
- app.get(apiRoutes_default.artifact.path, async (context) => {
2392
+ app.get(routes.artifact.path, async (context) => {
2364
2393
  const workspace = context.req.param("workspace");
2365
2394
  const runKey = context.req.param("runKey");
2366
2395
  const record = await runOf(workspace, runKey);
@@ -2369,7 +2398,7 @@ function createWorkflowHubApi(options = {}) {
2369
2398
  const requested = context.req.param("name");
2370
2399
  const resolved = resolveInside(runDir, requested);
2371
2400
  if (resolved === void 0) return context.json({ error: `'${requested}' is not inside this run.` }, 400);
2372
- if (context.req.query("raw") === "1") return streamArtifact(resolved, requested, context.req.header("range"), context.req.query("download") === "1") ?? context.json({ error: `'${requested}' has not been written.` }, 404);
2401
+ if (context.req.query("raw") === "1") return streamArtifact(resolved, requested, context.req.header("range"), context.req.query("download") === "1", context.req.header("if-match")) ?? context.json({ error: `'${requested}' has not been written.` }, 404);
2373
2402
  const body = readArtifact(resolved, requested);
2374
2403
  if (body === void 0) return context.json({ error: `'${requested}' has not been written.` }, 404);
2375
2404
  return context.json(body);
@@ -2491,14 +2520,26 @@ function readArtifact(resolved, requested) {
2491
2520
  };
2492
2521
  }
2493
2522
  /** Streams media with byte-range support so browser audio, video, and PDF controls can seek. */
2494
- function streamArtifact(resolved, requested, rangeHeader, download) {
2523
+ function streamArtifact(resolved, requested, rangeHeader, download, expectedVersion) {
2495
2524
  const stats = statOf(resolved);
2496
2525
  if (stats === void 0 || stats.isDirectory()) return void 0;
2526
+ const version = `"${stats.dev}-${stats.ino}-${stats.size}-${stats.mtimeMs}-${stats.ctimeMs}"`;
2527
+ if (expectedVersion !== void 0 && expectedVersion !== version) return new Response(null, {
2528
+ status: 412,
2529
+ headers: { etag: version }
2530
+ });
2497
2531
  const mimeType = artifactMimeType(requested);
2498
2532
  let start = 0;
2499
2533
  let end = Math.max(0, stats.size - 1);
2500
2534
  let partial = false;
2501
2535
  const match = rangeHeader?.match(/^bytes=(\d*)-(\d*)$/);
2536
+ if (rangeHeader !== void 0 && (!match || !match[1] && !match[2] || [match[1], match[2]].some((value) => value !== "" && !Number.isSafeInteger(Number(value))) || stats.size === 0)) return new Response(null, {
2537
+ status: 416,
2538
+ headers: {
2539
+ etag: version,
2540
+ "content-range": `bytes */${stats.size}`
2541
+ }
2542
+ });
2502
2543
  if (match !== null && match !== void 0 && stats.size > 0) {
2503
2544
  const requestedStart = match[1] === "" ? void 0 : Number(match[1]);
2504
2545
  const requestedEnd = match[2] === "" ? void 0 : Number(match[2]);
@@ -2507,7 +2548,7 @@ function streamArtifact(resolved, requested, rangeHeader, download) {
2507
2548
  start = requestedStart;
2508
2549
  end = requestedEnd === void 0 ? end : Math.min(requestedEnd, end);
2509
2550
  }
2510
- if (start >= stats.size || start > end) return new Response(null, {
2551
+ if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= stats.size || start > end) return new Response(null, {
2511
2552
  status: 416,
2512
2553
  headers: { "content-range": `bytes */${String(stats.size)}` }
2513
2554
  });
@@ -2515,6 +2556,7 @@ function streamArtifact(resolved, requested, rangeHeader, download) {
2515
2556
  }
2516
2557
  const filename = path.basename(requested).replace(/["\\\r\n]/g, "_");
2517
2558
  const headers = new Headers({
2559
+ etag: version,
2518
2560
  "accept-ranges": "bytes",
2519
2561
  "content-disposition": `${download || mimeType === "text/html" ? "attachment" : "inline"}; filename="${filename}"`,
2520
2562
  "content-length": String(stats.size === 0 ? 0 : end - start + 1),
@@ -2526,6 +2568,44 @@ function streamArtifact(resolved, requested, rangeHeader, download) {
2526
2568
  status: 200,
2527
2569
  headers
2528
2570
  });
2571
+ if (expectedVersion !== void 0) {
2572
+ if (!partial || end - start + 1 > 1048576) return new Response(null, {
2573
+ status: 416,
2574
+ headers: {
2575
+ etag: version,
2576
+ "content-range": `bytes */${stats.size}`
2577
+ }
2578
+ });
2579
+ const fd = fs.openSync(resolved, "r");
2580
+ try {
2581
+ const opened = fs.fstatSync(fd);
2582
+ if (`"${opened.dev}-${opened.ino}-${opened.size}-${opened.mtimeMs}-${opened.ctimeMs}"` !== expectedVersion) return new Response(null, {
2583
+ status: 412,
2584
+ headers: { etag: version }
2585
+ });
2586
+ const bytes = new Uint8Array(end - start + 1);
2587
+ let read = 0;
2588
+ while (read < bytes.length) {
2589
+ const count = fs.readSync(fd, bytes, read, bytes.length - read, start + read);
2590
+ if (count === 0) return new Response(null, {
2591
+ status: 412,
2592
+ headers: { etag: version }
2593
+ });
2594
+ read += count;
2595
+ }
2596
+ const after = fs.fstatSync(fd);
2597
+ if (after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) return new Response(null, {
2598
+ status: 412,
2599
+ headers: { etag: version }
2600
+ });
2601
+ return new Response(bytes, {
2602
+ status: 206,
2603
+ headers
2604
+ });
2605
+ } finally {
2606
+ fs.closeSync(fd);
2607
+ }
2608
+ }
2529
2609
  const body = Readable.toWeb(fs.createReadStream(resolved, {
2530
2610
  start,
2531
2611
  end
@@ -3276,7 +3356,7 @@ function createWorkflowServerRuntime(host, serverHost) {
3276
3356
  const response = await serverHost.context.requestApi({
3277
3357
  scope: "session",
3278
3358
  sessionId: owner
3279
- }, WORKFLOW_API_BASE_PATH, new Request(`${IN_PROCESS_ORIGIN}${apiRoutes_default.launch.path}`, {
3359
+ }, WORKFLOW_API_BASE_PATH, new Request(`${IN_PROCESS_ORIGIN}${routes.launch.path}`, {
3280
3360
  method: "POST",
3281
3361
  headers: { "content-type": "application/json" },
3282
3362
  body: JSON.stringify(parameters)