@phren/cli 0.3.14 → 0.3.16

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 (45) hide show
  1. package/README.md +1 -1
  2. package/dist/bridge/account-usage.d.ts +2 -1
  3. package/dist/bridge/account-usage.js +8 -1
  4. package/dist/bridge/claude-accounts.d.ts +3 -0
  5. package/dist/bridge/claude-accounts.js +13 -1
  6. package/dist/bridge/conductor-group.d.ts +2 -0
  7. package/dist/bridge/conductor-group.js +17 -5
  8. package/dist/bridge/conductor-sets.js +23 -3
  9. package/dist/bridge/dispatch-command.d.ts +1 -0
  10. package/dist/bridge/dispatch-command.js +40 -2
  11. package/dist/bridge/dispatch-returns.d.ts +21 -1
  12. package/dist/bridge/dispatch-returns.js +120 -12
  13. package/dist/bridge/dispatch.d.ts +76 -0
  14. package/dist/bridge/dispatch.js +7 -0
  15. package/dist/bridge/hand-off-queue.d.ts +3 -0
  16. package/dist/bridge/hand-off-queue.js +9 -0
  17. package/dist/bridge/owner-inbox-view.d.ts +6 -0
  18. package/dist/bridge/owner-inbox-view.js +32 -0
  19. package/dist/bridge/owner-inbox.d.ts +117 -0
  20. package/dist/bridge/owner-inbox.js +120 -0
  21. package/dist/bridge/return-contract.d.ts +35 -0
  22. package/dist/bridge/return-contract.js +10 -0
  23. package/dist/bridge/server-launch.js +12 -1
  24. package/dist/bridge/server-routes.d.ts +5 -0
  25. package/dist/bridge/server-routes.js +22 -1
  26. package/dist/bridge/server.js +37 -1
  27. package/dist/bridge/subscription.d.ts +13 -0
  28. package/dist/bridge/subscription.js +24 -0
  29. package/dist/bridge/terminal-herdr.js +1 -0
  30. package/dist/bridge/terminal-tmux.js +1 -0
  31. package/dist/bridge/terminal.d.ts +1 -0
  32. package/dist/bridge/terminal.js +1 -0
  33. package/dist/bridge/transcripts.js +8 -2
  34. package/dist/bridge/usage.d.ts +6 -0
  35. package/dist/bridge/usage.js +57 -10
  36. package/dist/bridge/worker-close.d.ts +10 -0
  37. package/dist/bridge/worker-close.js +77 -0
  38. package/dist/bridge/worker-reports.d.ts +10 -0
  39. package/dist/bridge/worker-reports.js +63 -0
  40. package/dist/bridge-hook.mjs +5089 -4489
  41. package/dist/cli-registry.js +9 -2
  42. package/dist/modules/registry.js +5 -5
  43. package/dist/tools/dispatch.js +33 -1
  44. package/package.json +1 -1
  45. package/starter/global/skills/conductor/SKILL.md +35 -0
package/README.md CHANGED
@@ -6,7 +6,7 @@ On startup it walks your phren directory, reads all `.md` files, and builds an i
6
6
 
7
7
  Periodic remote checks are off by default. Enable them with `phren config pull-interval 60` to check shared Git stores every minute while running, coordinated across MCP clients using the same store. Changed refs are fetched and applied only as clean fast-forwards; dirty or diverged stores are deferred. Pulled changes refresh the index and existing managed skill/instruction mirrors. Configure this machine with `phren config pull-interval 600` (ten minutes) or `phren config pull-interval off`. Periodic checks are disabled for project-local stores and the manual preset; existing lifecycle hooks are configured separately.
8
8
 
9
- Public surface: 59 MCP tools across 13 modules (search, tasks, findings, notes, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
9
+ Public surface: 76 MCP implementation tools across 16 catalog modules (search, tasks, findings, notes, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
10
10
 
11
11
  Notable shipped capabilities:
12
12
  - finding lifecycle tools: `supersede_finding`, `retract_finding`, `resolve_contradiction`, `get_contradictions`
@@ -1,7 +1,7 @@
1
1
  import { type NotLinkedComputer } from "./hand-off.js";
2
2
  import { type HookPeer } from "./peers.js";
3
3
  import { type Json } from "./protocol.js";
4
- import { NEAR_LIMIT_LEFT, type AccountUsage, type UsageWindow } from "./usage.js";
4
+ import { NEAR_LIMIT_LEFT, type AccountUsage, type Subscription, type UsageWindow } from "./usage.js";
5
5
  export { NEAR_LIMIT_LEFT };
6
6
  /**
7
7
  * Every computer's agent usage merged by account, for a conductor choosing
@@ -58,6 +58,7 @@ export interface AccountUsageRow {
58
58
  amountUSD: number;
59
59
  period: string;
60
60
  };
61
+ subscription?: Subscription;
61
62
  updatedAt?: string;
62
63
  /** How old the standing report is, as "4m" or "2d 3h". */
63
64
  age?: string;
@@ -29,7 +29,7 @@ export const STALE_AFTER_MS = 15 * 60_000;
29
29
  const SOURCES = USAGE_SOURCES.join(",");
30
30
  const USAGE_ROUTE = `/v1/usage?${new URLSearchParams({ sources: SOURCES, goPlan: "1", accounts: "all" })}`;
31
31
  const date = (value) => value ? Date.parse(value) : NaN;
32
- const hasData = (usage) => usage.windows.length > 0 || Boolean(usage.spend);
32
+ const hasData = (usage) => usage.windows.length > 0 || Boolean(usage.spend) || Boolean(usage.subscription);
33
33
  const newer = (a, b) => (date(b.usage.updatedAt) || 0) > (date(a.usage.updatedAt) || 0) ? b : a;
34
34
  export function ageText(ms) {
35
35
  const minutes = Math.max(0, Math.round(ms / 60_000));
@@ -106,6 +106,8 @@ export function mergeAccountUsage(reports, now = Date.now()) {
106
106
  continue;
107
107
  }
108
108
  const source = group[0].usage.source;
109
+ const subscriptions = group.filter(item => item.usage.subscription);
110
+ const subscription = subscriptions.sort((a, b) => (date(b.usage.subscription?.checkedAt) || date(b.usage.updatedAt) || 0) - (date(a.usage.subscription?.checkedAt) || date(a.usage.updatedAt) || 0))[0]?.usage.subscription;
109
111
  // One allowance: the freshest report with windows stands whole, never mixed with another read.
110
112
  const withWindows = reporting.filter(item => item.usage.windows.length);
111
113
  const standing = (withWindows.length ? withWindows : reporting).reduce(newer);
@@ -125,6 +127,7 @@ export function mergeAccountUsage(reports, now = Date.now()) {
125
127
  nearLimit: windows.some(w => w.limited) || leftPercent !== undefined && leftPercent < NEAR_LIMIT_LEFT,
126
128
  exhausted: exhausted.length > 0, ...(availableIn ? { availableIn } : {}),
127
129
  ...(spend ? { spend } : {}),
130
+ ...(subscription ? { subscription } : {}),
128
131
  ...(standing.usage.updatedAt ? { updatedAt: standing.usage.updatedAt } : {}),
129
132
  ...(Number.isFinite(updated) ? { age: ageText(now - updated) } : {}),
130
133
  stale: !Number.isFinite(updated) || now - updated > STALE_AFTER_MS || windows.some(w => w.reset),
@@ -228,6 +231,10 @@ export function formatAccountUsage(view) {
228
231
  const flags = [row.exhausted ? `out of quota${row.availableIn ? `, back in ${row.availableIn}` : ""}` : row.nearLimit ? `low, ${row.leftPercent ?? 0}% left` : row.leftPercent !== undefined ? `${row.leftPercent}% left` : "",
229
232
  row.stale ? `stale${row.age ? `, reported ${ago(row.age)}` : ""}` : row.age ? ago(row.age) : ""].filter(Boolean).join("; ");
230
233
  lines.push(`${title(row)} on ${where}${flags ? ` (${flags})` : ""}`);
234
+ if (row.subscription) {
235
+ const sub = row.subscription;
236
+ lines.push(` ${[sub.plan, sub.startedAt ? `since ${sub.startedAt.slice(0, 10)}` : "", sub.renewsAt ? `renews ${sub.renewsEstimated ? "about " : ""}${sub.renewsAt.slice(0, 10)}` : ""].filter(Boolean).join(" · ")}`);
237
+ }
231
238
  for (const w of row.windows) {
232
239
  const used = w.reset ? "reset, no new report" : w.usedPercent !== undefined ? `${w.usedPercent}% used` : w.usedUSD !== undefined ? `$${w.usedUSD.toFixed(2)}${w.limitUSD !== undefined ? ` of $${w.limitUSD.toFixed(2)}` : ""}` : "";
233
240
  lines.push(` ${w.name.padEnd(30)} ${used.padEnd(22)}${w.limited ? "limited now " : ""}${w.resetsIn ? `resets in ${w.resetsIn}` : ""}`.trimEnd());
@@ -1,3 +1,4 @@
1
+ import { type Subscription } from "./subscription.js";
1
2
  export declare const DEFAULT_ACCOUNT = "default";
2
3
  export interface ClaudeHome {
3
4
  /** "default", or the slug of ~/.claude-<slug>. */
@@ -32,6 +33,8 @@ export declare function setAccountLabel(id: string, label: string): Promise<void
32
33
  export declare function claudeAccountKey(home: ClaudeHome): string;
33
34
  /** The login's email, so the phone can name a card merged across computers. Usage rows only. */
34
35
  export declare function claudeAccountEmail(home: ClaudeHome): string | undefined;
36
+ /** The account home's own subscription, independent of the quota snapshot's age. */
37
+ export declare function claudeAccountSubscription(home: ClaudeHome, now?: Date): Subscription | undefined;
35
38
  export declare function claudeAccountRef(home: ClaudeHome, labels?: Record<string, string>): AccountRef;
36
39
  export declare const CODEX_ACCOUNT: AccountRef;
37
40
  /** Only for tests. */
@@ -10,6 +10,7 @@ import path from "node:path";
10
10
  import { dump, load } from "js-yaml";
11
11
  import { claudeConfigDir, homeDir } from "../home-paths.js";
12
12
  import { atomic, bridgeRoot } from "./protocol.js";
13
+ import { monthlyAnniversary, planName, subscriptionDate } from "./subscription.js";
13
14
  export const DEFAULT_ACCOUNT = "default";
14
15
  const SLUG = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
15
16
  export function isAccountSlug(value) { return value === DEFAULT_ACCOUNT || SLUG.test(value); }
@@ -127,7 +128,10 @@ function oauthIdentity(configFile) {
127
128
  const account = config.oauthAccount && typeof config.oauthAccount === "object" ? config.oauthAccount : {};
128
129
  const uuid = typeof account.accountUuid === "string" && account.accountUuid ? account.accountUuid : undefined;
129
130
  const email = typeof account.emailAddress === "string" && /^[^\s@]{1,64}@[^\s@]{1,190}$/.test(account.emailAddress) ? account.emailAddress : undefined;
130
- const value = { mtimeMs: stat.mtimeMs, size: stat.size, uuid, email };
131
+ const tier = planName(account.organizationRateLimitTier);
132
+ const billing = typeof account.billingType === "string" && /^(?:claude_)?(?:pro|max|team|enterprise)(?:_subscription)?$/.test(account.billingType)
133
+ ? planName(account.billingType.replace(/_subscription$/, "")) : undefined;
134
+ const value = { mtimeMs: stat.mtimeMs, size: stat.size, uuid, email, plan: tier ?? billing, startedAt: subscriptionDate(account.subscriptionCreatedAt) };
131
135
  identityCache.set(configFile, value);
132
136
  return value;
133
137
  }
@@ -142,6 +146,14 @@ export function claudeAccountKey(home) {
142
146
  }
143
147
  /** The login's email, so the phone can name a card merged across computers. Usage rows only. */
144
148
  export function claudeAccountEmail(home) { return oauthIdentity(home.configFile).email; }
149
+ /** The account home's own subscription, independent of the quota snapshot's age. */
150
+ export function claudeAccountSubscription(home, now = new Date()) {
151
+ const { plan, startedAt } = oauthIdentity(home.configFile);
152
+ if (!plan)
153
+ return undefined;
154
+ const renewsAt = startedAt ? monthlyAnniversary(startedAt, now) : undefined;
155
+ return { plan, ...(startedAt ? { startedAt } : {}), ...(renewsAt ? { renewsAt, renewsEstimated: true } : {}), checkedAt: now.toISOString() };
156
+ }
145
157
  export function claudeAccountRef(home, labels = readLabels()) {
146
158
  return { id: home.id, label: accountLabel(home.id, labels), key: claudeAccountKey(home) };
147
159
  }
@@ -100,6 +100,8 @@ export declare function buildSets(input: {
100
100
  };
101
101
  answers: readonly PeerAnswer[];
102
102
  computers: readonly Computer[];
103
+ /** Identity rows from peers, used only to recognize names in their set reports. */
104
+ reportedComputers?: readonly Pick<Computer, "id" | "name" | "aliases">[];
103
105
  }): {
104
106
  sets: ComputerSet[];
105
107
  unlinked: Computer[];
@@ -89,9 +89,19 @@ function conductorOf(entries) {
89
89
  * one-way peer. `unlinked` are computers the store knows with no link here.
90
90
  */
91
91
  export function buildSets(input) {
92
- const { local, answers } = input;
92
+ const { local } = input;
93
+ // A peer's directory can name this computer differently from its hostname.
94
+ // Only a matching id establishes that the peer's name belongs to self.
95
+ const reports = input.reportedComputers ?? [];
96
+ const selfReports = local.id ? reports.filter(row => row.id === local.id) : [];
97
+ const selfAnswers = input.answers.filter(answer => answer.ok && local.id && answer.id === local.id);
98
+ const selfNames = [...local.names, local.name, ...selfReports.flatMap(row => [row.name, ...row.aliases]),
99
+ ...selfAnswers.flatMap(answer => [answer.peer.name, answer.peer.address, ...(answer.ok ? answer.names : [])])];
100
+ const reportedSelf = indirectMembers(input.answers, local.names).find(name => selfReports.some(row => [row.name, ...row.aliases].some(alias => computerLabel(alias) === computerLabel(name))));
101
+ const selfName = reportedSelf ?? selfAnswers.map(answer => answer.peer.name).sort()[0] ?? local.name;
102
+ const answers = input.answers.filter(answer => !(answer.ok && local.id && answer.id === local.id));
93
103
  const members = answers.filter(answer => !oneWay(answer));
94
- const computers = [{ name: local.name, ...(local.id ? { id: local.id } : {}), local: true, reachable: true, link: "self",
104
+ const computers = [{ name: selfName, ...(local.id ? { id: local.id } : {}), local: true, reachable: true, link: "self",
95
105
  ...(local.conductor ? { conductor: local.conductor } : {}) }];
96
106
  for (const answer of members) {
97
107
  if (answer.ok)
@@ -101,13 +111,13 @@ export function buildSets(input) {
101
111
  else
102
112
  computers.push({ name: answer.peer.name, reachable: !!answer.disabled, link: "unknown", error: answer.error, ...(answer.code ? { code: answer.code } : {}) });
103
113
  }
104
- const indirect = indirectMembers(answers, local.names);
114
+ const indirect = indirectMembers(answers, selfNames);
105
115
  for (const name of indirect)
106
116
  computers.push({ name, link: "indirect", hint: linkHint(name) });
107
117
  const name = newest([local.set, ...members.map(answer => answer.ok ? answer.set : undefined)]);
108
118
  const own = { id: setId([local.id, ...members.map(answer => answer.ok ? answer.id : undefined)], local.name),
109
119
  ...(name?.name ? { name: name.name, namedAt: name.namedAt } : {}), local: true, computers,
110
- ...conductorOf([{ computer: local.name, conductor: local.conductor }, ...members.map(answer => ({ computer: answer.peer.name, conductor: answer.ok ? answer.conductor : undefined }))]) };
120
+ ...conductorOf([{ computer: selfName, conductor: local.conductor }, ...members.map(answer => ({ computer: answer.peer.name, conductor: answer.ok ? answer.conductor : undefined }))]) };
111
121
  const others = answers.flatMap(answer => {
112
122
  if (!answer.ok || !oneWay(answer))
113
123
  return [];
@@ -117,6 +127,8 @@ export function buildSets(input) {
117
127
  ...conductorOf([{ computer: answer.peer.name, conductor: answer.conductor }]) }];
118
128
  });
119
129
  const indirectLabels = new Set(indirect.map(computerLabel));
120
- const unlinked = input.computers.filter(row => !row.linked && ![row.name, ...row.aliases].some(known => indirectLabels.has(computerLabel(known))));
130
+ const selfLabels = new Set(selfNames.map(computerLabel));
131
+ const unlinked = input.computers.filter(row => !row.local && !row.linked && !(local.id && row.id === local.id)
132
+ && ![row.name, ...row.aliases].some(known => selfLabels.has(computerLabel(known)) || indirectLabels.has(computerLabel(known))));
121
133
  return { sets: [own, ...others], unlinked };
122
134
  }
@@ -1,10 +1,11 @@
1
1
  import { z } from "zod";
2
- import { askPeers, buildSets, localCaller } from "./conductor-group.js";
2
+ import { askPeers, buildSets, indirectMembers, localCaller } from "./conductor-group.js";
3
3
  import { readSetName, saveSetName } from "./conductor-role.js";
4
- import { readComputers } from "./computer-identity.js";
4
+ import { computerLabel, readComputers } from "./computer-identity.js";
5
5
  import { localNames } from "./computer-names.js";
6
6
  import { listsCaller } from "./health.js";
7
7
  import { optionalHookPeers, peerRequest } from "./peers.js";
8
+ import { object } from "./protocol.js";
8
9
  import { localConductor } from "./server-launch.js";
9
10
  const callerSchema = z.object({ name: z.string().max(253).optional(), hostKey: z.string().max(512).optional() });
10
11
  /** `GET /v1/conductor`: this computer's live conductor and what a peer needs
@@ -21,8 +22,27 @@ export async function readSets(info) {
21
22
  const [{ peers, peerError }, conductor, set, { computers }] = await Promise.all([optionalHookPeers(), localConductor(), readSetName(),
22
23
  readComputers({ local: { id: info.computer.id } })]);
23
24
  const answers = await askPeers(peers, await localCaller());
25
+ // Old /v1/conductor replies list peer names without ids. Resolve unknown
26
+ // names through the existing identity directory, also on older Hooks.
27
+ // Skip this extra round when names already identify every member.
28
+ const indirect = new Set(indirectMembers(answers, [info.computer.name, ...(info.computer.aliases ?? []), ...localNames()]).map(computerLabel));
29
+ const reportedComputers = (await Promise.all(answers.map(async (answer) => {
30
+ if (!answer.ok || answer.knowsCaller === false || !answer.peers?.some(name => indirect.has(computerLabel(name))))
31
+ return [];
32
+ try {
33
+ const directory = await peerRequest(answer.peer, "/v1/computers", undefined, 12_000);
34
+ return (Array.isArray(directory.computers) ? directory.computers.slice(0, 64) : []).flatMap(value => {
35
+ const row = object(value);
36
+ return typeof row.id === "string" && typeof row.name === "string" ? [{ id: row.id, name: row.name,
37
+ aliases: (Array.isArray(row.aliases) ? row.aliases : []).filter((name) => typeof name === "string").slice(0, 64) }] : [];
38
+ });
39
+ }
40
+ catch {
41
+ return [];
42
+ } // Missing or offline identity directory keeps the name-only view.
43
+ }))).flat();
24
44
  const view = buildSets({ local: { name: info.computer.name, id: info.computer.id, ...(conductor ? { conductor } : {}), ...(set ? { set } : {}),
25
- names: [info.computer.name, ...(info.computer.aliases ?? []), ...localNames()] }, answers, computers });
45
+ names: [info.computer.name, ...(info.computer.aliases ?? []), ...localNames()] }, answers, computers, reportedComputers });
26
46
  return { ...view, ...(peerError ? { peerError } : {}) };
27
47
  }
28
48
  const setNameValue = z.string().trim().min(1).max(60).refine(t => !/[\x00-\x1f\x7f]/.test(t)).nullable();
@@ -4,3 +4,4 @@ export declare function runHandOff(args: string[]): Promise<number>;
4
4
  /** One line per computer: name, reachability, link and conductor. */
5
5
  export declare function formatSets(view: Json): string;
6
6
  export declare function runConductor(args: string[]): Promise<number>;
7
+ export declare function runOwnerInbox(args: string[]): Promise<number>;
@@ -1,3 +1,5 @@
1
+ import { ownerInboxSchema } from "./owner-inbox.js";
2
+ import { prsSchema } from "./return-contract.js";
1
3
  import { parseArgs } from "node:util";
2
4
  import { hookRequest } from "./client.js";
3
5
  import { dispatchSchema } from "./dispatch.js";
@@ -6,6 +8,14 @@ import { terminalPaneFromEnv } from "./terminal.js";
6
8
  import { addGrant, grantSchema, listNamedGrants, removeGrant } from "./grants.js";
7
9
  import { sessionId } from "./protocol.js";
8
10
  export async function runDispatch(args) {
11
+ if (args[0] === "report") {
12
+ const { values } = parseArgs({ args: args.slice(1), options: { prs: { type: "string" } } });
13
+ const origin = await terminalPaneFromEnv();
14
+ if (!origin || !values.prs)
15
+ throw new Error("Usage inside a worker pane: phren dispatch report --prs <JSON array>");
16
+ console.log(JSON.stringify(await hookRequest("/v1/dispatch/report", { origin, prs: prsSchema.parse(JSON.parse(values.prs)) }), null, 2));
17
+ return 0;
18
+ }
9
19
  if (args.length === 1 && args[0] === "status") {
10
20
  console.log(JSON.stringify(await hookRequest("/v1/dispatch"), null, 2));
11
21
  return 0;
@@ -26,6 +36,7 @@ export async function runDispatch(args) {
26
36
  return 0;
27
37
  }
28
38
  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
39
+ "keep-open": { type: "boolean" },
29
40
  harness: { type: "string", default: "codex" }, model: { type: "string" }, effort: { type: "string" }, account: { type: "string" }, "permission-mode": { type: "string" }, prompt: { type: "string" }, label: { type: "string" },
30
41
  "parent-provider": { type: "string" }, "parent-session": { type: "string" }, "parent-computer": { type: "string" },
31
42
  "parent-server": { type: "string" }, "parent-workspace": { type: "string" }, "parent-tab": { type: "string" }, "parent-pane": { type: "string" },
@@ -41,8 +52,8 @@ export async function runDispatch(args) {
41
52
  server: values["parent-server"], workspace: values["parent-workspace"], tab: values["parent-tab"], pane: values["parent-pane"],
42
53
  source: values["parent-provider"], session: values["parent-session"],
43
54
  } : undefined;
44
- const { "permission-mode": permissionMode, ...rest } = values;
45
- const ordinary = { ...Object.fromEntries(Object.entries(rest).filter(([key]) => !key.startsWith("parent-"))), ...(permissionMode !== undefined ? { permissionMode } : {}) };
55
+ const { "permission-mode": permissionMode, "keep-open": keepOpen, ...rest } = values;
56
+ const ordinary = { ...Object.fromEntries(Object.entries(rest).filter(([key]) => !key.startsWith("parent-"))), ...(permissionMode !== undefined ? { permissionMode } : {}), ...(keepOpen ? { closeOnFinish: false } : {}) };
46
57
  const input = dispatchSchema.parse({ computer: positionals[0], project: positionals[1], ...ordinary,
47
58
  ...(parent ? { parent, parentTarget } : {}) });
48
59
  // Run inside an agent's pane, the dispatch remembers that pane for return notices.
@@ -112,6 +123,23 @@ export async function runConductor(args) {
112
123
  console.log(result.stopped ? "This computer has no conductor now." : "This computer had no conductor.");
113
124
  return 0;
114
125
  }
126
+ if (namespace === "integrator") {
127
+ const { values } = parseArgs({ args: args.slice(1), options: { session: { type: "string" }, computer: { type: "string" }, clear: { type: "boolean" } } });
128
+ if (values.clear) {
129
+ console.log(JSON.stringify(await hookRequest("/v1/conductor/integrator", { integrator: null }), null, 2));
130
+ return 0;
131
+ }
132
+ if (!values.session) {
133
+ console.log(JSON.stringify(await hookRequest("/v1/conductor/integrator"), null, 2));
134
+ return 0;
135
+ }
136
+ const { listLiveSessions } = await import("./hand-off.js");
137
+ const live = await listLiveSessions(), session = live.sessions.find(row => row.target?.session === values.session && (values.computer ? row.computer === values.computer : row.local));
138
+ if (!session?.target)
139
+ throw new Error("That integrator is not a live session on the selected computer.");
140
+ console.log(JSON.stringify(await hookRequest("/v1/conductor/integrator", { integrator: { target: session.target, ...(!session.local ? { computer: session.computer } : {}) } }), null, 2));
141
+ return 0;
142
+ }
115
143
  if (namespace === "sets") {
116
144
  if (action === "name") {
117
145
  const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { clear: { type: "boolean" } } });
@@ -161,3 +189,13 @@ export async function runConductor(args) {
161
189
  }
162
190
  throw new Error(CONDUCTOR_USAGE);
163
191
  }
192
+ export async function runOwnerInbox(args) {
193
+ const [action = "list", ...rest] = args;
194
+ const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { computer: { type: "string" }, project: { type: "string" }, id: { type: "string" }, resolution: { type: "string" }, all: { type: "boolean" } } });
195
+ const input = ownerInboxSchema.parse({ action, ...(values.computer ? { computer: values.computer === "local" ? undefined : values.computer } : {}),
196
+ ...(action === "add" ? { title: positionals.join(" "), project: values.project, id: values.id } : {}),
197
+ ...(action === "resolve" ? { id: positionals[0], resolution: values.resolution } : {}),
198
+ ...(values.all ? { includeResolved: true } : {}) });
199
+ console.log(JSON.stringify(await hookRequest("/v1/owner-inbox", input), null, 2));
200
+ return 0;
201
+ }
@@ -1,3 +1,4 @@
1
+ import { type PullRequest } from "./return-contract.js";
1
2
  import { sessionStalls } from "./stalls.js";
2
3
  import { z } from "zod";
3
4
  import { type OriginPane, type Receipt } from "./dispatch.js";
@@ -22,6 +23,9 @@ export { truncateUtf8 } from "./turn-records.js";
22
23
  export declare const REPLY_LIMIT = 4000;
23
24
  /** How often the dispatching Hook asks peers about open dispatches. */
24
25
  export declare const POLL_MS = 15000;
26
+ /** Allow the new process and its terminal identity to appear before declaring
27
+ * an unobserved launch gone. An observed worker never gets this grace. */
28
+ export declare const LAUNCH_GRACE_MS = 60000;
25
29
  /** Shortest gap between two notices typed into the same dispatching pane. */
26
30
  export declare const NOTICE_MS = 120000;
27
31
  /** Receipts older than this are no longer watched. */
@@ -68,7 +72,7 @@ export declare const workerRequestSchema: z.ZodObject<{
68
72
  /** What a worker pane shows right now, as its own computer reads it. */
69
73
  export interface WorkerObservation {
70
74
  /** Herdr's status for the pane, or gone when the pane or its conversation is no longer there. */
71
- state: "working" | "idle" | "done" | "blocked" | "unknown" | "gone" | "unavailable";
75
+ state: "working" | "idle" | "done" | "blocked" | "unknown" | "gone" | "closed" | "unavailable";
72
76
  session?: string;
73
77
  completed?: boolean;
74
78
  reply?: string;
@@ -79,6 +83,7 @@ export interface WorkerObservation {
79
83
  hook?: true;
80
84
  /** When the turn's Stop arrived, on the worker's clock; names the turn. */
81
85
  endedAt?: string;
86
+ stopSeq?: number;
82
87
  /** Background tasks the harness still runs: waited on while `working`,
83
88
  * left running when `done` after BACKGROUND_WAIT_MS. */
84
89
  background?: number;
@@ -86,12 +91,14 @@ export interface WorkerObservation {
86
91
  interrupted?: true;
87
92
  /** A permission request the pane's worker is waiting on, forwarded by its Hook (`AgentHooks.workerApproval`). */
88
93
  approval?: Json;
94
+ prs?: PullRequest[];
89
95
  stalled?: boolean;
90
96
  stalledSince?: string;
91
97
  stallFor?: number;
92
98
  }
93
99
  export interface WorkerReaders {
94
100
  snapshot: (server: string) => Promise<Json>;
101
+ freshSnapshot?: (server: string) => Promise<Json>;
95
102
  identity: (server: string, pane: Json) => Promise<string | undefined>;
96
103
  finalTurn: (source: Provider, session: string) => Promise<FinalTurn | undefined>;
97
104
  /** The turn record the pane's agent reported through its hooks (or OpenCode's plugin). */
@@ -103,6 +110,7 @@ export interface WorkerReaders {
103
110
  /** The turn a Codex pane lost with its app-server, which no Stop will end. */
104
111
  lost?: (server: string, pane: string, session?: string) => LostTurn | undefined;
105
112
  }
113
+ export declare function paneTurn(server: string, pane: Json, source: Provider): Promise<TurnRecord | undefined>;
106
114
  /** The default readers with the approval reader of the Hook that runs the workers. */
107
115
  export declare const workerReaders: (approval: NonNullable<WorkerReaders["approval"]>) => WorkerReaders;
108
116
  /** The receiving side of `/v1/dispatch/workers` on a Hook: leases the panes'
@@ -152,6 +160,11 @@ declare const approvalObservation: z.ZodObject<{
152
160
  export type ObservedApproval = z.infer<typeof approvalObservation>;
153
161
  /** What the owner is told when the worker's turn was interrupted in its terminal. */
154
162
  export declare const INTERRUPTED = "The worker's turn was interrupted in its terminal before it finished.";
163
+ export declare function workerTurnKey(seen: {
164
+ endedAt?: string;
165
+ stopSeq?: number;
166
+ reply?: string;
167
+ }, error?: string): string | undefined;
155
168
  /** Apply one observation to a receipt. Returns true when the receipt changed. */
156
169
  export declare function observe(receipt: Receipt, value: unknown, now: number): boolean;
157
170
  /** One line for the dispatching agent: who returned, how, and where to read it. */
@@ -182,6 +195,7 @@ export interface DispatchReturnsOptions {
182
195
  localAnswer?: (target: Target, actionId: string, decision: "approve" | "deny") => Promise<unknown>;
183
196
  /** A worker's new forwarded request was recorded. Returns true when this Hook pushed it to its phone. */
184
197
  onApproval?: (receipt: Receipt, approval: NonNullable<Receipt["approval"]>) => boolean | void;
198
+ close?: (receipt: Receipt) => Promise<Json>;
185
199
  now?: () => number;
186
200
  }
187
201
  /** One notice's delivery id, named by what it reports: the same returns keep the same id on a retry. */
@@ -200,6 +214,7 @@ export declare class DispatchReturns {
200
214
  private readonly grant;
201
215
  private readonly localAnswer?;
202
216
  private readonly onApproval?;
217
+ private readonly close?;
203
218
  private lastPoll;
204
219
  private readonly lastNotice;
205
220
  /** A return is waiting for a dispatching agent that was busy: try again on
@@ -232,6 +247,11 @@ export declare class DispatchReturns {
232
247
  /** Type one line into each idle dispatching agent that has returns it was
233
248
  * not told about. A pane still working is tried again on the next tick. */
234
249
  notify(): Promise<void>;
250
+ /** Forward a structured report with one stable id; queued is a durable
251
+ * acceptance, while uncertain is retained and never replaced. */
252
+ forwardPrs(): Promise<void>;
253
+ cleanup(): Promise<void>;
254
+ private closeRemote;
235
255
  /** Every unread return, oldest first, marked read as it is handed over. */
236
256
  take(): Promise<Json[]>;
237
257
  }