omo-ai 5.1.78 → 5.1.81

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 (72) hide show
  1. package/bin/darwin/omo-keychain +0 -0
  2. package/bin/lib/doctor.js +6 -17
  3. package/bin/lib/engine-commands.js +2 -0
  4. package/bin/lib/engine-environment.js +3 -0
  5. package/bin/lib/path-omo.js +53 -0
  6. package/bin/lib/provider-map.json +1 -1
  7. package/bin/lib/reflection-lock.generated.js +7 -7
  8. package/bin/lib/self-update.js +18 -2
  9. package/bin/lib/service-auth.generated.js +45 -43
  10. package/bin/lib/thread-output.js +9 -1
  11. package/bin/lib/thread.js +23 -3
  12. package/bin/lib/versioned-install.js +173 -0
  13. package/bin/lib/versioned-leftovers.js +58 -0
  14. package/package.json +2 -2
  15. package/plugin/CHANGELOG.md +140 -0
  16. package/plugin/README.md +2 -1
  17. package/plugin/extensions/gateway-store-worker.mjs +2 -2
  18. package/plugin/extensions/memory-run-supervisor.mjs +1 -1
  19. package/plugin/extensions/omo-claim-receipt.js +2 -2
  20. package/plugin/extensions/omo-computer-run-worker.mjs +1 -1
  21. package/plugin/extensions/omo-computer-use.js +1 -1
  22. package/plugin/extensions/omo-desktop-toolkit.js +1 -1
  23. package/plugin/extensions/omo-device-account.js +7 -7
  24. package/plugin/extensions/omo-device-service.js +6 -6
  25. package/plugin/extensions/omo-feedback.js +2 -2
  26. package/plugin/extensions/omo-init-deep-advisor.js +2 -2
  27. package/plugin/extensions/omo-member.js +2 -2
  28. package/plugin/extensions/omo-memory-commands.js +2 -2
  29. package/plugin/extensions/omo-memory-doctor.js +3 -3
  30. package/plugin/extensions/omo-memory-memfs.js +1 -1
  31. package/plugin/extensions/omo-memory-palace.js +2 -2
  32. package/plugin/extensions/omo-memory-sync.js +1 -1
  33. package/plugin/extensions/omo-onboarding-scan.js +2 -2
  34. package/plugin/extensions/omo-recall-store.js +1 -1
  35. package/plugin/extensions/omo-session-history.js +1 -1
  36. package/plugin/extensions/omo-side-panel.js +2 -2
  37. package/plugin/extensions/omo-task.js +2 -2
  38. package/plugin/extensions/omo-telemetry-otlp.js +2 -2
  39. package/plugin/extensions/omo-telemetry-posthog.js +1 -1
  40. package/plugin/extensions/omo-telemetry-recovery.js +1 -1
  41. package/plugin/extensions/omo-thread-client.js +3 -3
  42. package/plugin/extensions/omo-wake.js +6 -6
  43. package/plugin/extensions/omo.js +3 -3
  44. package/plugin/package.json +3 -2
  45. package/plugin/runtime/agent-toolkit-sdk/sdk.js +2 -2
  46. package/plugin/runtime/ast-grep-mcp/manifest.json +1 -1
  47. package/plugin/runtime/bunshin-ts/sdk.js +2 -2
  48. package/plugin/runtime/category-coverage/index.js +4 -4
  49. package/plugin/runtime/omo-sdk/sdk.js +65 -0
  50. package/plugin/runtime/rollback-migrate.js +1 -1
  51. package/plugin/runtime/task-config/index.js +1 -1
  52. package/plugin/runtime/thread-sdk/sdk.js +3 -3
  53. package/plugin/scripts/install.mjs +3 -1
  54. package/plugin/skills/browser/runtime/omowright/manifest.json +1 -1
  55. package/plugin/skills/omo-relay/SKILL.md +38 -0
  56. package/plugin/skills/omo-relay/references/errors.md +16 -0
  57. package/plugin/skills/omo-relay/references/machines.md +53 -0
  58. package/plugin/skills/omo-relay/references/parallel.md +51 -0
  59. package/plugin/skills/omo-relay/scripts/sdk/bind-eval.ts +153 -0
  60. package/plugin/skills/omo-relay/scripts/sdk/index.ts +5 -0
  61. package/plugin/skills/omo-relay/scripts/sdk/machines.ts +123 -0
  62. package/plugin/skills/omo-relay/scripts/sdk/outcome.ts +77 -0
  63. package/plugin/skills/omo-relay/scripts/sdk/ports.ts +78 -0
  64. package/plugin/skills/omo-relay/scripts/sdk/threads.ts +89 -0
  65. package/plugin/skills/omo-relay/scripts/sdk/tsconfig.json +19 -0
  66. package/plugin/skills/programming/SKILL.md +1 -0
  67. package/plugin/skills/ultrawork/SKILL.md +0 -22
  68. package/plugin/skills/ultrawork/references/gpt.md +67 -0
  69. package/plugin/skills/ulw-execute/SKILL.md +15 -5
  70. package/plugin/telemetry-schema.json +2 -1
  71. package/plugin/telemetry-schema.omo-cloud.json +2 -1
  72. package/plugin/skills/ultrawork/references/astra-variant.md +0 -66
@@ -92,7 +92,8 @@ const agentDir = process.env.OMO_CODING_AGENT_DIR ?? process.env.SENPI_CODING_AG
92
92
  ?? process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".omo", "agent")
93
93
  const env = {
94
94
  ...process.env,
95
- SENPI_BRAND: JSON.stringify(brand),
95
+ // The plugin this launcher prepends with --extension is the engine's own, never a user flag (#14465).
96
+ SENPI_BRAND: JSON.stringify({ ...brand, extensions: [plugin] }),
96
97
  OMO_NATIVE: "1",
97
98
  OMO_CODING_AGENT_DIR: agentDir,
98
99
  SENPI_CODING_AGENT_DIR: agentDir,
@@ -338,6 +339,7 @@ var REQUIRED_PLUGIN_ARTIFACTS = [
338
339
  join4("skills-conditional", "x-search", "SKILL.md"),
339
340
  join4("runtime", "agent-toolkit-sdk", "sdk.js"),
340
341
  join4("runtime", "bunshin-ts", "sdk.js"),
342
+ join4("runtime", "omo-sdk", "sdk.js"),
341
343
  join4("runtime", "thread-sdk", "sdk.js"),
342
344
  join4("runtime", "ast-grep-mcp", "cli.js"),
343
345
  join4("runtime", "lsp-daemon", "dist", "cli.js"),
@@ -6,5 +6,5 @@
6
6
  "page-bundle.js": "c517fa11a62a1b83dc79f72b288159a420831426418b1d4d9d492fc6c414f78c",
7
7
  "LICENSE": "b083425948376611de9b92b0aeb7377e604505756ea427e541a34d9b030d4dc1"
8
8
  },
9
- "stagedAtUtc": "2026-11-18T23:53:35.200Z"
9
+ "stagedAtUtc": "2026-11-21T21:49:43.967Z"
10
10
  }
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: omo-relay
3
+ description: "Works on the account's other devices through omo's built-in relay from a js eval cell: run a command or a long job on another machine, read, write, edit or search its files, copy a directory tree to or from it, and run one operation on every machine, on chosen machines or on several threads at once with one outcome per target. Use when the user names another device, machine, host or computer of the account, asks for something on every machine or on all or several threads at once, or wants a fan-out or a remote command or file."
4
+ metadata:
5
+ short-description: Machines, threads and fan-out across the account's devices
6
+ ---
7
+
8
+ # omo-relay
9
+
10
+ Every device signed in to the same account answers through the relay. From a js eval cell you reach them with two things that ship with omo, and this skill's typed helpers bind both:
11
+
12
+ - **The fleet client**: list the machines, then run commands and file operations on one of them or on many in one wave.
13
+ - **The thread tools** (`tool.thread_*`): the agent sessions on every device. This skill covers the parallel helpers over them; one thread at a time is the thread tools' own job.
14
+
15
+ ## Bind once per cell
16
+
17
+ ```js
18
+ const relay = await import("<this skill's directory>/scripts/sdk/index.ts")
19
+ const fleet = relay.fleetFromSdk(await import(`${env("OMO_BUNSHIN_TS_SDK_ROOT")}/sdk.js`)) // the account's machines
20
+ const threads = relay.threadPortFromTools(tool) // the account's threads
21
+ ```
22
+
23
+ Use the directory you read this file from. `OMO_BUNSHIN_TS_SDK_ROOT` is set only inside an omo session; outside one there is no fleet client to reach, so say so instead of retrying.
24
+
25
+ ## Where to read next
26
+
27
+ | You need to | Read |
28
+ |---|---|
29
+ | List the machines, run a command or a long job, move files, search a machine | [references/machines.md](references/machines.md) |
30
+ | Do the same thing on every machine, on chosen machines or on several threads, and report each one | [references/parallel.md](references/parallel.md) |
31
+ | Act on an error code (`not_found`, `unsupported`, `invalid_arguments`, a skipped machine) | [references/errors.md](references/errors.md) |
32
+
33
+ ## Rules that hold everywhere
34
+
35
+ - Report every target. A batch answers `fulfilled`, `rejected` and `skipped`; a machine that was offline or failed is part of the answer, so name it with its reason.
36
+ - Branch on `code`, then do what `next_action` says. The message is for people; the code is the contract.
37
+ - Never retry a whole wave because one target failed: rerun only that target, after its `next_action`.
38
+ - Treat a machine's files and processes as the user's. Clean up what you create there and read the removal back.
@@ -0,0 +1,16 @@
1
+ # Errors
2
+
3
+ A failure carries `code`, `message` and `next_action`. In a batch it is the rejected outcome's `error`; from a direct machine call it is the thrown `BunshinSessionError`, with the same fields. Branch on `code` and follow `next_action`.
4
+
5
+ | Where | Code or reason | What it means | Do |
6
+ |---|---|---|---|
7
+ | a skipped machine | `machine_offline` | The device is not connected; nothing ran there. | Report it. Do not retry in a loop. |
8
+ | a skipped machine | `machine_unsupported` | The device's service cannot run machine operations. | Report it; omo on that device needs an update. |
9
+ | a machine call | `unsupported` | A direct call on a machine that cannot run it (seen on an offline device). | Read the row's `state` and `unsupported` first and pick another machine. |
10
+ | a machine call | `invalid_arguments` | The arguments do not match the operation (the message names the field). | Fix the arguments; resending the same call fails the same way. |
11
+ | a lookup | `not_found` | No machine has that id or alias. | Use an id or alias from `listMachines()`. |
12
+ | a lookup | `ambiguous` | Several machines share that alias. | Use the id. |
13
+ | a callback | `callback_failed` | Your callback threw something without a code. | Read the message; rerun for that target only. |
14
+ | any | `uncertain: true` | The operation may have run before the failure. | Check its effect on that machine before running it again. |
15
+
16
+ For a code not listed here, do what its `next_action` says.
@@ -0,0 +1,53 @@
1
+ # Machines
2
+
3
+ Everything below was observed between two devices of one account, `device-a` calling `device-b`.
4
+
5
+ ## List them and pick one
6
+
7
+ ```js
8
+ const rows = await fleet.listMachines()
9
+ // [{ id, alias, os, arch, state: "online" | "offline", unsupported?: true, kind, connection, tags, ... }]
10
+ ```
11
+
12
+ The list includes this device. `id` is a 32-character hex string and never changes; `alias` is the device's display name and two devices can share one, so keep the `id` once you have it. A row with `state: "offline"` or `unsupported: true` cannot run operations: read both before you plan work on it.
13
+
14
+ Run on one machine through `onMachine`, which answers one outcome and never throws:
15
+
16
+ ```js
17
+ const r = await relay.onMachine(fleet, "device-b", (m) => m.shell("df -h /"))
18
+ if (r.kind === "fulfilled") print(r.value.stdout)
19
+ else print(r.kind === "rejected" ? `${r.error.code}: ${r.error.next_action}` : `skipped: ${r.reason}`)
20
+ ```
21
+
22
+ Inside the callback `m` is the machine; the calls below are its methods.
23
+
24
+ ## Run a command
25
+
26
+ | Call | Answers | Use it for |
27
+ |---|---|---|
28
+ | `m.shell(cmd, { cwd?, env?, timeoutMs? })` | `{ exitCode, stdout, stderr, signal, timedOut, truncated, durationMs }` | One command that finishes. A non-zero `exitCode` is an answer, not a throw: check it. |
29
+ | `m.spawn(cmd, { cwd? })` | a handle: `await h.status()` -> `{ state: "running", output, elapsedMs, ... }`; `await h.wait()` -> `{ exitCode, output, durationMs, truncated }` | A job that outlives one call: builds, test runs, installs. Its `output` comes from a terminal, so lines end in `\r\n`. |
30
+ | `m.exec_command({ cmd, yield_ms })` | `{ handleId, state, output, ... }` after `yield_ms` (an integer from 250 to 10000) | Start a command and come back to it; stop it with `m.kill_terminal({ handle_id })`, which answers `{ state: "task-failed", reason: "killed" }`. Prefer `spawn` unless you need the handle id. |
31
+ | `m.processInfo()` | `{ pid, command, rssBytes, cpuTimeMs, startedAtMs, lastOpAtMs }` of the device service | Checking that the machine's device service is the one you expect. |
32
+
33
+ ## Move and search files
34
+
35
+ Paths are absolute paths on that machine.
36
+
37
+ | Call | Answers |
38
+ |---|---|
39
+ | `m.write(path, textOrBytes, { createParentDirs: true })` | `{ path, bytesWritten }` |
40
+ | `m.readText(path)` / `m.read(path)` | the text / the bytes |
41
+ | `m.edit(path, { exact, replacement })` | `{ path, content, replacements, writeResult }`; `exact` must occur in the file |
42
+ | `m.glob(pattern)` | `{ entries: [path, ...], truncated }` |
43
+ | `m.grep(dir, pattern)` | `{ matches: [{ path, line, text }], truncated }` |
44
+ | `m.pushTree(localDir, remoteDir)` | `{ fileCount, dirCount, symlinkCount, writtenBytes, verifiedFiles }`: copies a directory of this device to that machine |
45
+ | `m.pullTree(remoteDir, localDir)` | `{ fileCount, writtenBytes }`: copies a directory of that machine here |
46
+
47
+ ## Clean up
48
+
49
+ Put scratch files under one directory you create for the task, remove it in the same callback that finished the work, and read the removal back, because a leftover file on someone's machine is yours:
50
+
51
+ ```js
52
+ await relay.onMachine(fleet, "device-b", (m) => m.shell(`rm -rf '${dir}' && test ! -e '${dir}' && echo removed`))
53
+ ```
@@ -0,0 +1,51 @@
1
+ # Parallel work
2
+
3
+ Every helper answers a `BatchResult`: one outcome per target, in the order you gave the targets (the device list's order for the every-* helpers), and one target's failure never rejects the batch.
4
+
5
+ ```ts
6
+ type Settled<Target, Value> =
7
+ | { kind: "fulfilled"; target: Target; value: Value }
8
+ | { kind: "rejected"; target: Target; error: { code: string; message: string; next_action: string; uncertain?: true } }
9
+ | { kind: "skipped"; target: Target; reason: string }
10
+ type BatchResult<Target, Value> = { outcomes: Settled[]; fulfilled: Settled[]; rejected: Settled[]; skipped: Settled[]; ok: boolean }
11
+ ```
12
+
13
+ `ok` is true only when nothing was rejected or skipped.
14
+
15
+ ## Machines
16
+
17
+ | Shape | Call | Target in each outcome |
18
+ |---|---|---|
19
+ | Every machine of the account | `relay.onEveryMachine(fleet, op, { timeoutMs?, concurrency? })` | `{ id, alias, state }` |
20
+ | The machines you name (ids or aliases) | `relay.onMachines(fleet, ["device-b", id], op, { timeoutMs?, concurrency? })` | the name you passed |
21
+ | One machine | `relay.onMachine(fleet, "device-b", op)` | the name you passed; answers one `Settled`, not a batch |
22
+
23
+ `op` is `async (m, { signal }) => value`. `timeoutMs` is per machine: when it passes, that machine settles as rejected and the others carry on. Every machine starts at once unless you pass `concurrency`.
24
+
25
+ Observed on a seven-device account, `onEveryMachine(fleet, (m) => m.shell("uname -s"), { timeoutMs: 30000 })` answered in under a second: five fulfilled (this device among them), one skipped `machine_offline`, one skipped `machine_unsupported`. With a callback that threw on `device-b` only, `device-b` came back rejected with the thrown message and the other outcomes were unchanged.
26
+
27
+ A name that matches no machine is rejected with `not_found`; an alias two machines share is rejected with `ambiguous` (use the id). Neither runs anything.
28
+
29
+ ## Threads
30
+
31
+ Bind the port with `relay.threadPortFromTools(tool)`; each helper calls the thread tools for you and turns a tool error into that thread's rejected outcome.
32
+
33
+ | Shape | Call |
34
+ |---|---|
35
+ | Send one message to several threads | `relay.sendToThreads(threads, [thread, ...], message, { delivery?, all_scope?, concurrency? })` |
36
+ | Read several threads | `relay.readThreads(threads, [thread, ...], { wait_ms?, max_bytes?, all_scope?, concurrency? })` |
37
+ | Any thread call on several threads | `relay.onThreads([thread, ...], (thread) => threads.read(thread), { concurrency? })` |
38
+ | Every listed thread | `relay.onEveryThread(threads, (row) => ..., { list: { all_scope?, state? }, concurrency? })` |
39
+
40
+ A thread is named by the `thread` value of a `tool.thread_list()` row. `onEveryThread` lists once and rejects only when that list fails (`ThreadListError` with its `code` and `next_action`): then nothing ran.
41
+
42
+ ## Report the batch
43
+
44
+ ```js
45
+ const r = await relay.onEveryMachine(fleet, (m) => m.shell("uname -a"), { timeoutMs: 30000 })
46
+ print(r.outcomes.map((o) => `${o.target.alias}: ${
47
+ o.kind === "fulfilled" ? o.value.stdout.trim() : o.kind === "rejected" ? `failed ${o.error.code} (${o.error.next_action})` : `skipped ${o.reason}`
48
+ }`).join("\n"))
49
+ ```
50
+
51
+ Give the user one line per target, failures and skips included.
@@ -0,0 +1,153 @@
1
+ import type {
2
+ FleetPort,
3
+ MachineRef,
4
+ PortAnswer,
5
+ PortError,
6
+ ThreadListOptions,
7
+ ThreadListValue,
8
+ ThreadPort,
9
+ ThreadReadOptions,
10
+ ThreadReadValue,
11
+ ThreadRow,
12
+ ThreadSendOptions,
13
+ ThreadSendValue,
14
+ } from "./ports.ts"
15
+
16
+ /** What an eval cell's `tool.thread_*` call answers: the tool result, whose `text` is the result as JSON. */
17
+ export type ToolText = { readonly text: string }
18
+
19
+ export type EvalThreadTools = {
20
+ thread_list(args: ThreadListOptions): Promise<ToolText>
21
+ thread_read(args: { readonly thread: string } & ThreadReadOptions): Promise<ToolText>
22
+ thread_send(args: { readonly thread: string; readonly message: string } & ThreadSendOptions): Promise<ToolText>
23
+ }
24
+
25
+ export class RelayBindError extends Error {
26
+ readonly code: "sdk_shape"
27
+ readonly next_action: string
28
+
29
+ constructor(code: RelayBindError["code"], message: string, nextAction: string) {
30
+ super(message)
31
+ this.name = "RelayBindError"
32
+ this.code = code
33
+ this.next_action = nextAction
34
+ }
35
+ }
36
+
37
+ type Fields = Readonly<Record<string, unknown>>
38
+ type ErrorBranch = { readonly kind: "error"; readonly error: PortError }
39
+
40
+ function isFields(value: unknown): value is Fields {
41
+ return typeof value === "object" && value !== null && !Array.isArray(value)
42
+ }
43
+
44
+ function unreadable(tool: string, detail: string): ErrorBranch {
45
+ return {
46
+ kind: "error",
47
+ error: {
48
+ code: "unreadable_result",
49
+ message: `${tool} answered something that is not a thread tool result: ${detail}`,
50
+ next_action: `call tool.${tool} directly and read its text; report the answer if it is not JSON`,
51
+ },
52
+ }
53
+ }
54
+
55
+ function portErrorFrom(value: unknown): PortError | undefined {
56
+ if (!isFields(value)) return undefined
57
+ const { code, message, next_action: nextAction } = value
58
+ if (typeof code !== "string" || typeof message !== "string" || typeof nextAction !== "string") return undefined
59
+ return { code, message, next_action: nextAction, ...(value["uncertain"] === true ? { uncertain: true } : {}) }
60
+ }
61
+
62
+ type Parsed = { readonly ok: true; readonly fields: Fields } | { readonly ok: false; readonly answer: ErrorBranch }
63
+
64
+ function parseAnswer(tool: string, result: ToolText): Parsed {
65
+ let parsed: unknown
66
+ try {
67
+ parsed = JSON.parse(result.text)
68
+ } catch (thrown) {
69
+ if (thrown instanceof SyntaxError) return { ok: false, answer: unreadable(tool, thrown.message) }
70
+ throw thrown
71
+ }
72
+ if (!isFields(parsed)) return { ok: false, answer: unreadable(tool, "not an object") }
73
+ if (parsed["kind"] === "error") {
74
+ const error = portErrorFrom(parsed["error"])
75
+ const answer =
76
+ error === undefined
77
+ ? unreadable(tool, "an error without code, message and next_action")
78
+ : { kind: "error" as const, error }
79
+ return { ok: false, answer }
80
+ }
81
+ if (parsed["kind"] !== "ok") return { ok: false, answer: unreadable(tool, `kind ${String(parsed["kind"])}`) }
82
+ return { ok: true, fields: parsed }
83
+ }
84
+
85
+ function rowOf(value: unknown): ThreadRow | undefined {
86
+ if (!isFields(value)) return undefined
87
+ const { thread, name, machine } = value
88
+ if (typeof thread !== "string" || typeof name !== "string") return undefined
89
+ return { thread, name, ...(typeof machine === "string" ? { machine } : {}) }
90
+ }
91
+
92
+ function listAnswer(result: ToolText): PortAnswer<ThreadListValue> {
93
+ const parsed = parseAnswer("thread_list", result)
94
+ if (!parsed.ok) return parsed.answer
95
+ const { fields } = parsed
96
+ const rawRows = fields["threads"]
97
+ if (!Array.isArray(rawRows)) return unreadable("thread_list", "no threads array")
98
+ const threads: ThreadRow[] = []
99
+ for (const raw of rawRows) {
100
+ const row = rowOf(raw)
101
+ if (row === undefined) return unreadable("thread_list", "a row without thread and name")
102
+ threads.push(row)
103
+ }
104
+ return { ...fields, kind: "ok", threads }
105
+ }
106
+
107
+ function readAnswer(result: ToolText): PortAnswer<ThreadReadValue> {
108
+ const parsed = parseAnswer("thread_read", result)
109
+ if (!parsed.ok) return parsed.answer
110
+ const { fields } = parsed
111
+ const { thread, items } = fields
112
+ if (typeof thread !== "string" || !Array.isArray(items)) return unreadable("thread_read", "no thread or items")
113
+ return { ...fields, kind: "ok", thread, items }
114
+ }
115
+
116
+ function sendAnswer(result: ToolText): PortAnswer<ThreadSendValue> {
117
+ const parsed = parseAnswer("thread_send", result)
118
+ if (!parsed.ok) return parsed.answer
119
+ const { fields } = parsed
120
+ const { thread } = fields
121
+ if (typeof thread !== "string") return unreadable("thread_send", "no thread")
122
+ return { ...fields, kind: "ok", thread }
123
+ }
124
+
125
+ /** The thread port over an eval cell's `tool` object: `threadPortFromTools(tool)`. */
126
+ export function threadPortFromTools(tool: EvalThreadTools): ThreadPort {
127
+ return {
128
+ list: async (options) => listAnswer(await tool.thread_list(options ?? {})),
129
+ read: async (thread, options) => readAnswer(await tool.thread_read({ ...options, thread })),
130
+ send: async (thread, message, options) => sendAnswer(await tool.thread_send({ ...options, thread, message })),
131
+ }
132
+ }
133
+
134
+ function isFleet(value: unknown): value is FleetPort<MachineRef> {
135
+ return isFields(value) && typeof value["listMachines"] === "function" && typeof value["fanout"] === "function"
136
+ }
137
+
138
+ /**
139
+ * The account's fleet client from the module the cell imported:
140
+ * `fleetFromSdk(await import(\`${env("OMO_BUNSHIN_TS_SDK_ROOT")}/sdk.js\`))`. The cell does the import so the skill
141
+ * holds no non-literal import() (the remote-module guard freezes those).
142
+ */
143
+ export function fleetFromSdk(sdk: unknown): FleetPort<MachineRef> {
144
+ const fleet = isFields(sdk) ? sdk["bunshin"] : undefined
145
+ if (!isFleet(fleet)) {
146
+ throw new RelayBindError(
147
+ "sdk_shape",
148
+ "the module passed in does not export a bunshin client with listMachines and fanout",
149
+ "in an omo session's eval cell, import sdk.js from OMO_BUNSHIN_TS_SDK_ROOT and pass that module; update omo if it still fails",
150
+ )
151
+ }
152
+ return fleet
153
+ }
@@ -0,0 +1,5 @@
1
+ export { fleetFromSdk, RelayBindError, threadPortFromTools, type EvalThreadTools, type ToolText } from "./bind-eval.ts"
2
+ export { onEveryMachine, onMachine, onMachines, type MachineLabel, type MachineOp } from "./machines.ts"
3
+ export { type BatchOptions, type BatchResult, type Settled } from "./outcome.ts"
4
+ export type * from "./ports.ts"
5
+ export { onEveryThread, onThreads, readThreads, sendToThreads, ThreadListError, type ThreadOp } from "./threads.ts"
@@ -0,0 +1,123 @@
1
+ import { batchOf, portErrorOf, type BatchResult, type Settled } from "./outcome.ts"
2
+ import type { FleetPort, MachineRef, PortError, WaveContext, WaveOptions, WaveOutcome } from "./ports.ts"
3
+
4
+ export type MachineOp<Machine, Value> = (machine: Machine, context: WaveContext) => Promise<Value>
5
+
6
+ /** How a machine is named in an outcome: the row's identity, never the live proxy. */
7
+ export type MachineLabel = Pick<MachineRef, "id" | "alias" | "state">
8
+
9
+ type Resolution<Machine> =
10
+ { readonly kind: "machine"; readonly machine: Machine } | { readonly kind: "rejected"; readonly error: PortError }
11
+
12
+ // The fleet client's contract is one outcome per dispatched machine; a slot left empty would otherwise
13
+ // vanish from the batch, so it is reported instead of dropped.
14
+ const NO_OUTCOME: PortError = {
15
+ code: "no_outcome",
16
+ message: "the fleet client settled no outcome for this machine",
17
+ next_action: "report it; check the machine with listMachines() before running the operation again",
18
+ }
19
+
20
+ function labelOf(machine: MachineRef): MachineLabel {
21
+ return { id: machine.id, alias: machine.alias, state: machine.state }
22
+ }
23
+
24
+ function settledOf<Target, Value>(target: Target, outcome: WaveOutcome<unknown, Value>): Settled<Target, Value> {
25
+ switch (outcome.kind) {
26
+ case "fulfilled":
27
+ return { kind: "fulfilled", target, value: outcome.value }
28
+ case "rejected":
29
+ return { kind: "rejected", target, error: portErrorOf(outcome.error) }
30
+ case "skipped":
31
+ return { kind: "skipped", target, reason: outcome.reason ?? "duplicate" }
32
+ }
33
+ }
34
+
35
+ function resolve<Machine extends MachineRef>(rows: readonly Machine[], idOrAlias: string): Resolution<Machine> {
36
+ const matches = rows.filter((row) => row.id === idOrAlias || row.alias === idOrAlias)
37
+ const [machine] = matches
38
+ if (machine === undefined) {
39
+ return {
40
+ kind: "rejected",
41
+ error: {
42
+ code: "not_found",
43
+ message: `no machine of this account has the id or alias ${idOrAlias}`,
44
+ next_action: "use an id or alias from listMachines()",
45
+ },
46
+ }
47
+ }
48
+ if (matches.length > 1) {
49
+ return {
50
+ kind: "rejected",
51
+ error: {
52
+ code: "ambiguous",
53
+ message: `${matches.length} machines share the alias ${idOrAlias}`,
54
+ next_action: "address the machine by its id from listMachines()",
55
+ },
56
+ }
57
+ }
58
+ return { kind: "machine", machine }
59
+ }
60
+
61
+ /** Runs `op` on every machine of the account in one wave; offline and unsupported machines come back skipped. */
62
+ export async function onEveryMachine<Machine extends MachineRef, Value>(
63
+ fleet: FleetPort<Machine>,
64
+ op: MachineOp<Machine, Value>,
65
+ options?: WaveOptions,
66
+ ): Promise<BatchResult<MachineLabel, Value>> {
67
+ const outcomes: { readonly index: number; readonly settled: Settled<MachineLabel, Value> }[] = []
68
+ for await (const outcome of fleet.fanout("all", async (machine, context) => op(machine, context), options)) {
69
+ outcomes.push({ index: outcome.index, settled: settledOf(labelOf(outcome.machine), outcome) })
70
+ }
71
+ return batchOf(outcomes.sort((left, right) => left.index - right.index).map(({ settled }) => settled))
72
+ }
73
+
74
+ /**
75
+ * Runs `op` on the named machines (ids or aliases) in one wave and answers one outcome per name, in input
76
+ * order. A name that matches no machine, or more than one, is rejected without running anything for it.
77
+ */
78
+ export async function onMachines<Machine extends MachineRef, Value>(
79
+ fleet: FleetPort<Machine>,
80
+ targets: readonly string[],
81
+ op: MachineOp<Machine, Value>,
82
+ options?: WaveOptions,
83
+ ): Promise<BatchResult<string, Value>> {
84
+ const slots = new Array<Settled<string, Value> | undefined>(targets.length).fill(undefined)
85
+ const dispatched: { readonly slot: number; readonly machine: Machine }[] = []
86
+ try {
87
+ const rows = await fleet.listMachines()
88
+ targets.forEach((target, slot) => {
89
+ const resolution = resolve(rows, target)
90
+ if (resolution.kind === "rejected") slots[slot] = { kind: "rejected", target, error: resolution.error }
91
+ else dispatched.push({ slot, machine: resolution.machine })
92
+ })
93
+ if (dispatched.length > 0) {
94
+ const wave = fleet.fanout(
95
+ dispatched.map(({ machine }) => machine),
96
+ async (machine, context) => op(machine, context),
97
+ options,
98
+ )
99
+ for await (const outcome of wave) {
100
+ const entry = dispatched[outcome.index]
101
+ if (entry !== undefined) slots[entry.slot] = settledOf(targets[entry.slot] ?? entry.machine.id, outcome)
102
+ }
103
+ }
104
+ } catch (thrown) {
105
+ // The directory read or the wave itself failed: every target still unsettled carries that one cause.
106
+ const error = portErrorOf(thrown)
107
+ targets.forEach((target, slot) => {
108
+ if (slots[slot] === undefined) slots[slot] = { kind: "rejected", target, error }
109
+ })
110
+ }
111
+ return batchOf(targets.map((target, slot) => slots[slot] ?? { kind: "rejected", target, error: NO_OUTCOME }))
112
+ }
113
+
114
+ /** `onMachines` for one machine: one outcome, never a throw. */
115
+ export async function onMachine<Machine extends MachineRef, Value>(
116
+ fleet: FleetPort<Machine>,
117
+ idOrAlias: string,
118
+ op: MachineOp<Machine, Value>,
119
+ options?: WaveOptions,
120
+ ): Promise<Settled<string, Value>> {
121
+ const { outcomes } = await onMachines(fleet, [idOrAlias], op, options)
122
+ return outcomes[0] ?? { kind: "rejected", target: idOrAlias, error: NO_OUTCOME }
123
+ }
@@ -0,0 +1,77 @@
1
+ import type { PortError } from "./ports.ts"
2
+
3
+ export type Settled<Target, Value> =
4
+ | { readonly kind: "fulfilled"; readonly target: Target; readonly value: Value }
5
+ | { readonly kind: "rejected"; readonly target: Target; readonly error: PortError }
6
+ | { readonly kind: "skipped"; readonly target: Target; readonly reason: string }
7
+
8
+ export type BatchResult<Target, Value> = {
9
+ readonly outcomes: readonly Settled<Target, Value>[]
10
+ readonly fulfilled: readonly Extract<Settled<Target, Value>, { kind: "fulfilled" }>[]
11
+ readonly rejected: readonly Extract<Settled<Target, Value>, { kind: "rejected" }>[]
12
+ readonly skipped: readonly Extract<Settled<Target, Value>, { kind: "skipped" }>[]
13
+ readonly ok: boolean
14
+ }
15
+
16
+ export type BatchOptions = { readonly concurrency?: number }
17
+
18
+ const CALLBACK_NEXT_ACTION = "the callback failed on this target only; read the message, then rerun it for this target"
19
+
20
+ export function batchOf<Target, Value>(outcomes: readonly Settled<Target, Value>[]): BatchResult<Target, Value> {
21
+ const fulfilled: Extract<Settled<Target, Value>, { kind: "fulfilled" }>[] = []
22
+ const rejected: Extract<Settled<Target, Value>, { kind: "rejected" }>[] = []
23
+ const skipped: Extract<Settled<Target, Value>, { kind: "skipped" }>[] = []
24
+ for (const outcome of outcomes) {
25
+ if (outcome.kind === "fulfilled") fulfilled.push(outcome)
26
+ else if (outcome.kind === "rejected") rejected.push(outcome)
27
+ else skipped.push(outcome)
28
+ }
29
+ return { outcomes, fulfilled, rejected, skipped, ok: rejected.length === 0 && skipped.length === 0 }
30
+ }
31
+
32
+ function stringField(value: object, key: string): string | undefined {
33
+ const field: unknown = Reflect.get(value, key)
34
+ return typeof field === "string" && field.length > 0 ? field : undefined
35
+ }
36
+
37
+ /** Reads `{ code, message, next_action, uncertain }` off anything a callback or the fleet client threw. */
38
+ export function portErrorOf(thrown: unknown): PortError {
39
+ if (typeof thrown !== "object" || thrown === null) {
40
+ return { code: "callback_failed", message: String(thrown), next_action: CALLBACK_NEXT_ACTION }
41
+ }
42
+ const message = stringField(thrown, "message") ?? String(thrown)
43
+ const uncertain = Reflect.get(thrown, "uncertain") === true
44
+ return {
45
+ code: stringField(thrown, "code") ?? "callback_failed",
46
+ message,
47
+ next_action: stringField(thrown, "next_action") ?? CALLBACK_NEXT_ACTION,
48
+ ...(uncertain ? { uncertain } : {}),
49
+ }
50
+ }
51
+
52
+ /**
53
+ * Runs `task` for every item with at most `concurrency` in flight (unbounded when omitted, as the fleet
54
+ * client's own default is) and keeps input order. Callers pass tasks that settle to data and never reject.
55
+ */
56
+ export async function settleEach<Item, Result>(
57
+ items: readonly Item[],
58
+ task: (item: Item) => Promise<Result>,
59
+ concurrency: number | undefined,
60
+ ): Promise<Result[]> {
61
+ if (concurrency === undefined) return Promise.all(items.map(task))
62
+ if (!Number.isInteger(concurrency) || concurrency < 1) {
63
+ throw new RangeError(`concurrency must be a positive integer, got ${concurrency}`)
64
+ }
65
+ const results = new Array<Result>(items.length)
66
+ let next = 0
67
+ const worker = async (): Promise<void> => {
68
+ while (next < items.length) {
69
+ const index = next
70
+ next += 1
71
+ const item = items[index]
72
+ if (item !== undefined) results[index] = await task(item)
73
+ }
74
+ }
75
+ await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker))
76
+ return results
77
+ }
@@ -0,0 +1,78 @@
1
+ // The narrow shapes the helpers need from the shipped fleet client and from the thread tools. The helpers
2
+ // depend on these ports, never on the shipped bundles (which carry no type declarations), so a change in
3
+ // how the product exposes machines or threads moves `bind-eval.ts` only.
4
+
5
+ /** The part of a machine row every helper reads. */
6
+ export type MachineRef = {
7
+ readonly id: string
8
+ readonly alias: string
9
+ readonly state: "online" | "offline"
10
+ }
11
+
12
+ /** Handed to every machine callback; aborts when the wave's `timeoutMs` passes for that machine. */
13
+ export type WaveContext = { readonly signal: AbortSignal }
14
+
15
+ /** One machine's outcome as the fleet client yields it while a wave runs; `index` is its place in the wave. */
16
+ export type WaveOutcome<Machine, Value> =
17
+ | { readonly kind: "fulfilled"; readonly machine: Machine; readonly value: Value; readonly index: number }
18
+ | { readonly kind: "rejected"; readonly machine: Machine; readonly error: Error; readonly index: number }
19
+ | { readonly kind: "skipped"; readonly machine: Machine; readonly reason?: string; readonly index: number }
20
+
21
+ export type WaveOptions = {
22
+ readonly concurrency?: number
23
+ readonly timeoutMs?: number
24
+ }
25
+
26
+ export type FleetPort<Machine extends MachineRef> = {
27
+ listMachines(): Promise<readonly Machine[]>
28
+ fanout<Value>(
29
+ targets: readonly Machine[] | "all",
30
+ fn: (machine: Machine, context: WaveContext) => Promise<Value>,
31
+ options?: WaveOptions,
32
+ ): AsyncIterable<WaveOutcome<Machine, Value>>
33
+ }
34
+
35
+ /** A failure in the shape every thread tool and every fleet error carries. */
36
+ export type PortError = {
37
+ readonly code: string
38
+ readonly message: string
39
+ readonly next_action: string
40
+ readonly uncertain?: boolean
41
+ }
42
+
43
+ export type PortOk<Value> = { readonly kind: "ok" } & Value
44
+
45
+ export type PortAnswer<Value> = PortOk<Value> | { readonly kind: "error"; readonly error: PortError }
46
+
47
+ /** The part of a `thread_list` row the helpers read; `thread` is the value every thread tool takes back. */
48
+ export type ThreadRow = {
49
+ readonly thread: string
50
+ readonly name: string
51
+ readonly machine?: string
52
+ }
53
+
54
+ export type ThreadListOptions = {
55
+ readonly all_scope?: boolean
56
+ readonly state?: readonly ("running" | "idle" | "inactive" | "archived")[]
57
+ }
58
+
59
+ export type ThreadReadOptions = {
60
+ readonly wait_ms?: number
61
+ readonly max_bytes?: number
62
+ readonly all_scope?: boolean
63
+ }
64
+
65
+ export type ThreadSendOptions = {
66
+ readonly delivery?: "auto" | "steer" | "follow_up"
67
+ readonly all_scope?: boolean
68
+ }
69
+
70
+ export type ThreadListValue = { readonly threads: readonly ThreadRow[] }
71
+ export type ThreadReadValue = { readonly thread: string; readonly items: readonly unknown[] }
72
+ export type ThreadSendValue = { readonly thread: string }
73
+
74
+ export type ThreadPort = {
75
+ list(options?: ThreadListOptions): Promise<PortAnswer<ThreadListValue>>
76
+ read(thread: string, options?: ThreadReadOptions): Promise<PortAnswer<ThreadReadValue>>
77
+ send(thread: string, message: string, options?: ThreadSendOptions): Promise<PortAnswer<ThreadSendValue>>
78
+ }