@phren/cli 0.3.58 → 0.3.61

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 (91) hide show
  1. package/README.md +1 -1
  2. package/dist/bridge/account-add.d.ts +30 -0
  3. package/dist/bridge/account-add.js +125 -19
  4. package/dist/bridge/account-failover.d.ts +9 -2
  5. package/dist/bridge/account-failover.js +1 -1
  6. package/dist/bridge/account-policy.d.ts +44 -0
  7. package/dist/bridge/account-policy.js +103 -0
  8. package/dist/bridge/account-pools.d.ts +35 -0
  9. package/dist/bridge/account-pools.js +171 -0
  10. package/dist/bridge/account-usage.d.ts +29 -4
  11. package/dist/bridge/account-usage.js +117 -8
  12. package/dist/bridge/agent-hook-callback.d.ts +6 -0
  13. package/dist/bridge/agent-hook-callback.js +10 -2
  14. package/dist/bridge/agent-hook-stores.d.ts +3 -0
  15. package/dist/bridge/agent-hook-stores.js +13 -0
  16. package/dist/bridge/agent-hooks.d.ts +12 -2
  17. package/dist/bridge/agent-hooks.js +41 -4
  18. package/dist/bridge/claude-account-setup.d.ts +16 -0
  19. package/dist/bridge/claude-account-setup.js +46 -2
  20. package/dist/bridge/claude-accounts.d.ts +9 -0
  21. package/dist/bridge/claude-accounts.js +53 -15
  22. package/dist/bridge/claude-credits.d.ts +8 -2
  23. package/dist/bridge/claude-credits.js +52 -31
  24. package/dist/bridge/codex-threads.js +50 -2
  25. package/dist/bridge/command.js +12 -3
  26. package/dist/bridge/continuation-launch.d.ts +32 -0
  27. package/dist/bridge/continuation-launch.js +112 -1
  28. package/dist/bridge/dispatch-command.js +22 -0
  29. package/dist/bridge/dispatch-returns.d.ts +23 -0
  30. package/dist/bridge/dispatch-returns.js +57 -0
  31. package/dist/bridge/dispatch.d.ts +26 -4
  32. package/dist/bridge/dispatch.js +100 -11
  33. package/dist/bridge/git-host-gitlab.js +2 -1
  34. package/dist/bridge/git-hosts.d.ts +8 -0
  35. package/dist/bridge/git-hosts.js +16 -2
  36. package/dist/bridge/git-publish.js +18 -2
  37. package/dist/bridge/git.d.ts +8 -0
  38. package/dist/bridge/git.js +24 -1
  39. package/dist/bridge/hand-off-queue.d.ts +71 -0
  40. package/dist/bridge/hand-off-queue.js +38 -0
  41. package/dist/bridge/harnesses.d.ts +12 -0
  42. package/dist/bridge/harnesses.js +20 -4
  43. package/dist/bridge/helper.d.ts +54 -0
  44. package/dist/bridge/helper.js +186 -0
  45. package/dist/bridge/herdr.js +6 -2
  46. package/dist/bridge/hook-fast.d.ts +3 -0
  47. package/dist/bridge/hook-fast.js +10 -2
  48. package/dist/bridge/move-computers.d.ts +15 -1
  49. package/dist/bridge/move-computers.js +123 -26
  50. package/dist/bridge/owner-inbox-sources.d.ts +12 -1
  51. package/dist/bridge/owner-inbox-sources.js +127 -49
  52. package/dist/bridge/peers.d.ts +2 -0
  53. package/dist/bridge/peers.js +35 -4
  54. package/dist/bridge/prompt-deliveries.d.ts +69 -2
  55. package/dist/bridge/prompt-deliveries.js +342 -28
  56. package/dist/bridge/schedule-watch.js +17 -3
  57. package/dist/bridge/server-routes.d.ts +6 -0
  58. package/dist/bridge/server-routes.js +98 -14
  59. package/dist/bridge/server-stream.js +6 -4
  60. package/dist/bridge/server.js +2 -1
  61. package/dist/bridge/session-move.d.ts +70 -1
  62. package/dist/bridge/session-move.js +311 -19
  63. package/dist/bridge/simulators.d.ts +19 -0
  64. package/dist/bridge/simulators.js +93 -13
  65. package/dist/bridge/speech-live.js +132 -22
  66. package/dist/bridge/task-routes.d.ts +16 -16
  67. package/dist/bridge/terminal-herdr.js +6 -1
  68. package/dist/bridge/terminal-tmux.js +9 -5
  69. package/dist/bridge/terminal.d.ts +9 -2
  70. package/dist/bridge/transcript-claude.d.ts +3 -0
  71. package/dist/bridge/transcript-claude.js +175 -29
  72. package/dist/bridge/transcript-preview.d.ts +11 -2
  73. package/dist/bridge/transcript-preview.js +90 -8
  74. package/dist/bridge/turn-records.d.ts +19 -0
  75. package/dist/bridge/turn-records.js +78 -3
  76. package/dist/bridge/usage.d.ts +17 -0
  77. package/dist/bridge/usage.js +3 -2
  78. package/dist/bridge-hook.mjs +11964 -10084
  79. package/dist/cli-registry.js +2 -2
  80. package/dist/content/citation.d.ts +4 -0
  81. package/dist/content/citation.js +21 -21
  82. package/dist/data/task-contract.d.ts +4 -4
  83. package/dist/governance/policy.js +5 -2
  84. package/dist/index.js +1 -1
  85. package/dist/modules/registry.js +5 -5
  86. package/dist/project-config.d.ts +14 -0
  87. package/dist/project-config.js +40 -1
  88. package/dist/tools/dispatch.js +1 -1
  89. package/dist/tools/helper.d.ts +3 -0
  90. package/dist/tools/helper.js +44 -0
  91. package/package.json +1 -1
@@ -2,8 +2,10 @@ import { terminalProvider } from "./terminal.js";
2
2
  import { peerFingerprint } from "./dispatch-hosts.js";
3
3
  import { redactPeerHandoff } from "./peer-handoff.js";
4
4
  import { relocationSupport } from "./worker-relocation.js";
5
- import { continuationIntent, continuationLaunchSchema, continuationPlacement, launchContinuation } from "./continuation-launch.js";
6
- import { addClaudeAccount } from "./account-add.js";
5
+ import { CONVERSATION_FILE, CONVERSATION_MARKER, continuationConversationPage, continuationIntent, continuationLaunchSchema, continuationPlacement, fetchContinuationConversation, launchContinuation, withConversationPointer } from "./continuation-launch.js";
6
+ import { addClaudeAccount, signInClaudeAccount } from "./account-add.js";
7
+ import { ACCOUNT_ROLES, isAccountRole, setAccountSettings, setComputerAllowedPools } from "./account-pools.js";
8
+ import { claudeHome } from "./claude-accounts.js";
7
9
  import { localMoveAvailability, moveComputers } from "./move-computers.js";
8
10
  import { ownerRequest, requestPeer } from "./request-origin.js";
9
11
  import { listMoves, moveSessionFields, readMove } from "./session-move.js";
@@ -14,6 +16,7 @@ import { reportWorker, readIntegrator, setIntegrator } from "./worker-reports.js
14
16
  import { sessionStalls } from "./stalls.js";
15
17
  import { harnessInventoryWithin, launchCheckOff } from "./harnesses.js";
16
18
  import path from "node:path";
19
+ import { stat } from "node:fs/promises";
17
20
  import { z } from "zod";
18
21
  import { sudoAnswer } from "./sudo.js";
19
22
  import { saveCodeNote } from "./code-note.js";
@@ -24,7 +27,7 @@ import { resolveCodeStore, CodeRoutes } from "./code-routes.js";
24
27
  import { dispatchProjectDirectory, dispatchStatus, originPaneSchema } from "./dispatch.js";
25
28
  import { hookWorkers } from "./dispatch-returns.js";
26
29
  import { remoteChildren } from "./dispatch-tree.js";
27
- import { briefArrival, briefId, readLaunchBrief } from "./launch-brief.js";
30
+ import { briefArrival, briefId, briefRoot, launchesWithBrief, readLaunchBrief } from "./launch-brief.js";
28
31
  import { listApprovalRules, changeApprovalRule } from "./approval-rules.js";
29
32
  import { addGrant, listGrants, listNamedGrants, removeGrant } from "./grants.js";
30
33
  import { clearProjectAuthority, confirmAuthority, listConfirmations, projectAuthority, readAuthority, setProjectAuthority } from "./authority.js";
@@ -42,8 +45,8 @@ import { paneAccountField, paneChatState, panes, rpc, servers, snapshot, validat
42
45
  import { locateProject } from "./locate.js";
43
46
  import { gitStatus } from "./git.js";
44
47
  import { gitRoot, launchDirectory, repositoryBranch, webServers, withGitReadDeadline } from "./projects.js";
45
- import { approvalDecisions, BridgeError, bridgeRoot, MAX_FRAME, object, objects, PROTOCOL, provider, serverName, targetFromURL, targetSchema } from "./protocol.js";
46
- import { bootedSimulators, simulatorAct, simulatorApps, simulatorScreenshot } from "./simulators.js";
48
+ import { approvalDecisions, atomicInPrivateDir, BridgeError, bridgeRoot, MAX_FRAME, object, objects, PROTOCOL, provider, serverName, targetFromURL, targetSchema } from "./protocol.js";
49
+ import { bootedSimulators, simulatorAct, simulatorApps, simulatorDevices, simulatorScreenshot } from "./simulators.js";
47
50
  import { childAgentTree, historicalImage, publicChildAgents, refreshTranscript, runningChildAgents, targetTranscriptPath } from "./transcripts.js";
48
51
  import { listUploads, removeUpload, saveUpload, uploadImage } from "./uploads.js";
49
52
  import { currentModel, currentStep } from "./steps.js";
@@ -89,7 +92,7 @@ async function childActivity(source, session) {
89
92
  export const capabilities = { transcript: true, progress: true, images: true, prompt: true, stop: true,
90
93
  terminal: "ssh-pty", shell: "ssh-pty", paneTerminal: "ssh-pty", paneLayout: true, deskPresence: true, herdr: true, sessionRename: true, diff: true, webServers: true, webPreview: "ssh-exec", activity: true,
91
94
  approvals: true, questions: false, accountUsage: true, providers: ["codex", "claude", "copilot", "opencode"],
92
- files: true, repositoryFiles: true, fileResolution: true, subagents: true, sideQuestions: true, dispatch: true, conductorSets: true, setLink: true, ownerInbox: true, workerReports: true, queuedHandOff: true, approvalPush: "direct-apns", simulators: process.platform === "darwin", simulatorStream: process.platform === "darwin", code: true, codeFiles: true, overviewStream: true, speech: true, speechTimestamps: true, speechTimestampStream: true, speechLive: true, speechVoices: true, speechFormats: [...SPEECH_FORMATS], transcribe: true, memoryStore: true, promptOnce: true, promptStatus: true, deliveryFrames: true, paneDeliveries: true, resources: true, sudo: true, sudoOutcome: true, previewDeltas: true, quickChat: true, agentFolder: true, launchPermissionMode: true, sessionMove: true, moveNewChat: true, moveConductor: true, moveToComputer: true, moveConductorToComputer: true, moveResume: true, claudeAccountAdd: true, workerRelocation: 1, projectMemory: true, fileWrite: true, fileSearch: true, gitReview: true, memoryStoreBatch: true, gitHosts: true, projectHostToken: true };
95
+ files: true, repositoryFiles: true, fileResolution: true, subagents: true, sideQuestions: true, dispatch: true, conductorSets: true, setLink: true, ownerInbox: true, workerReports: true, queuedHandOff: true, approvalPush: "direct-apns", simulators: process.platform === "darwin", simulatorStream: process.platform === "darwin", simulatorDevices: process.platform === "darwin", simulatorDrag: process.platform === "darwin", code: true, codeFiles: true, overviewStream: true, speech: true, speechTimestamps: true, speechTimestampStream: true, speechLive: true, speechVoices: true, speechFormats: [...SPEECH_FORMATS], transcribe: true, memoryStore: true, promptOnce: true, promptStatus: true, deliveryFrames: true, paneDeliveries: true, resources: true, sudo: true, sudoOutcome: true, previewDeltas: true, quickChat: true, agentFolder: true, launchPermissionMode: true, sessionMove: true, moveNewChat: true, moveConductor: true, moveToComputer: true, moveConductorToComputer: true, moveResume: true, moveSummaryByTarget: true, moveConversationCopy: true, claudeAccountAdd: true, accountPools: true, workerRelocation: 1, projectMemory: true, fileWrite: true, fileSearch: true, gitReview: true, memoryStoreBatch: true, gitHosts: true, projectHostToken: true, gitRemoteIdentity: true };
93
96
  export function capabilitiesForModules(snapshot) {
94
97
  const allowed = new Set(snapshot.modules.flatMap(module => module.capabilities));
95
98
  const result = Object.fromEntries(Object.entries(capabilities).filter(([name]) => allowed.has(name)));
@@ -329,11 +332,13 @@ async function moveDestination(move, caller) {
329
332
  if (!peer || object((await peerRequest(peer, "/v1/health", undefined, 5_000)).computer).id !== move.computerId)
330
333
  throw new BridgeError(403, "The move destination's enrollment changed.");
331
334
  }
332
- async function peerContinuationIntent(caller, id) {
335
+ /** Destinations whose enrollment was checked for a move's conversation pages, until when. */
336
+ const verifiedPages = new Map();
337
+ async function peerContinuationIntent(caller, id, conversation) {
333
338
  const candidates = (await hookPeers()).filter(peer => peerFingerprint(peer) === caller.fingerprint && (!caller.name || caller.name === peer.name));
334
339
  if (candidates.length !== 1)
335
340
  throw new BridgeError(403, "The launch origin is not uniquely verified.");
336
- return peerRequest(candidates[0], `/v1/sessions/move/intent?id=${z.string().uuid().parse(id)}`, undefined, 5_000);
341
+ return peerRequest(candidates[0], `/v1/sessions/move/intent?id=${z.string().uuid().parse(id)}${conversation === undefined ? "" : `&conversation=${conversation}`}`, undefined, 5_000);
337
342
  }
338
343
  export function createRouteHandler(ctx) {
339
344
  const { version, modules, info, computerID, scheduleStore, scheduler, dispatches, agentHooks, journal, modelCatalog, accountUsage, resources, launches, locatedDirectories, fanoutMessages, canary } = ctx;
@@ -467,8 +472,19 @@ export function createRouteHandler(ctx) {
467
472
  const caller = requestPeer(request), move = await readMove(id);
468
473
  if (!move || move.state === "failed")
469
474
  throw new BridgeError(403, "This continuation intent is no longer authorized.");
470
- await moveDestination(move, caller);
471
- result = await continuationIntent(id);
475
+ // `conversation=<offset>`: a page of the conversation a summary-by-target move copies (continuation-launch.ts).
476
+ // The destination's enrollment is checked again (one SSH call back to it) at most once a minute while it pages.
477
+ const page = url.searchParams.get("conversation");
478
+ const verifiedKey = JSON.stringify([id, caller?.fingerprint, caller?.name, caller?.id]);
479
+ if (page === null || (verifiedPages.get(verifiedKey) ?? 0) <= Date.now()) {
480
+ await moveDestination(move, caller);
481
+ if (page !== null) {
482
+ verifiedPages.set(verifiedKey, Date.now() + 60_000);
483
+ if (verifiedPages.size > 64)
484
+ verifiedPages.delete(verifiedPages.keys().next().value);
485
+ }
486
+ }
487
+ result = page === null ? await continuationIntent(id) : await continuationConversationPage(id, z.coerce.number().int().nonnegative().parse(page));
472
488
  break;
473
489
  }
474
490
  case "/v1/sessions/move/launch": {
@@ -604,8 +620,9 @@ export function createRouteHandler(ctx) {
604
620
  case "/v1/web-servers":
605
621
  result = { servers: await webServers() };
606
622
  break;
623
+ // `all=1` (capability simulatorDevices): every available device with its state, for the phone's picker.
607
624
  case "/v1/simulators":
608
- result = { simulators: await bootedSimulators() };
625
+ result = { simulators: url.searchParams.get("all") === "1" ? await simulatorDevices() : await bootedSimulators() };
609
626
  break;
610
627
  case "/v1/simulators/screenshot": {
611
628
  const bytes = await simulatorScreenshot(String(url.searchParams.get("udid") ?? ""));
@@ -947,6 +964,30 @@ export function createRouteHandler(ctx) {
947
964
  harness: note.target && "harness" in note.target ? note.target.harness : "codex", prompt, label: `Code note: ${note.symbol}`.slice(0, 200) });
948
965
  } : undefined);
949
966
  }
967
+ else if (url.pathname === "/v1/sessions/move" && data.interrupt === true) {
968
+ // "Stop <agent> and hand off now": Escape only while the move's hand-off request is still held.
969
+ if (!ownerRequest(request, data))
970
+ throw new BridgeError(403, "Only the owner can interrupt a move's agent.");
971
+ if (!ctx.mover)
972
+ throw new BridgeError(503, "Session moves are unavailable.");
973
+ const { id } = z.object({ id: z.string().uuid(), interrupt: z.literal(true), origin: z.unknown().optional() }).strict().parse(data);
974
+ // Esc as /v1/keys sends it: a served OpenCode pane or a Codex pane on the Hook's own app-server stops
975
+ // its turn over its API; otherwise the key goes to the pane. A question the Hook holds is declined
976
+ // first, and the turn is still stopped: a declined question alone lets the turn carry on.
977
+ const escape = async (target) => {
978
+ if (await agentHooks.servedKeys(target, ["Escape"], "working", { abortTurn: true }))
979
+ return;
980
+ agentHooks.cancelHeldQuestion(target);
981
+ const { codexServers } = await import("./codex-servers.js");
982
+ const owned = codexServers.forTarget(target);
983
+ if (owned && await codexServers.interrupt(owned).catch(() => false)) {
984
+ agentHooks.clearTerminalPrompt(target);
985
+ return;
986
+ }
987
+ await terminalProvider().sendKeys(target.server, target.pane, ["esc"]);
988
+ };
989
+ result = { ok: true, ...await ctx.mover.interrupt(id, ctx.handOffs, escape) };
990
+ }
950
991
  else if (url.pathname === "/v1/sessions/move") {
951
992
  // Answers once the move is checked and recorded; the hand-off and relaunch run on, and GET says where it is.
952
993
  if (!ctx.mover)
@@ -981,7 +1022,17 @@ export function createRouteHandler(ctx) {
981
1022
  const role = await (await import("./conductor-role.js")).readRoleState();
982
1023
  const prepared = role?.succession?.side === "successor" && role.succession.id === input.brief.id && role.succession.phase !== "aborted";
983
1024
  const cwd = prepared ? defaultPhrenPath() : await dispatchProjectDirectory(input.project);
984
- return launchSession(selectedServer(url), { cwd, kind: input.to.harness, account: input.to.account, model: input.to.model, effort: input.to.effort, label: `move-${input.brief.id}`, brief: input.brief }, { trustFolder: true, onPlaced: async (target) => {
1025
+ // A summary-by-target move's whole conversation, from the source Hook that admitted it; none from an older one.
1026
+ // Asked for only for those moves (the brief is the source's own, checked against its intent above), and only
1027
+ // for a harness launched with a brief file: its folder is where the copy goes and the brief carries the line.
1028
+ const wantsCopy = !!caller && input.brief.text.includes(CONVERSATION_MARKER) && launchesWithBrief(input.to.harness);
1029
+ const conversation = wantsCopy ? await fetchContinuationConversation(offset => peerContinuationIntent(caller, input.brief.id, offset), redactPeerHandoff) : undefined;
1030
+ const copied = conversation ? path.join(briefRoot(), input.brief.id, CONVERSATION_FILE) : undefined;
1031
+ const brief = copied ? { ...input.brief, text: withConversationPointer(input.brief.text, copied) } : input.brief;
1032
+ return launchSession(selectedServer(url), { cwd, kind: input.to.harness, account: input.to.account, model: input.to.model, effort: input.to.effort, label: `move-${input.brief.id}`, brief }, { trustFolder: true, onPlaced: async (target) => {
1033
+ // Into the brief folder, which the new agent may read (Claude's --add-dir), as soon as it exists.
1034
+ if (copied && conversation && await stat(path.dirname(copied)).catch(() => undefined))
1035
+ await atomicInPrivateDir(copied, conversation).catch(() => undefined);
985
1036
  await onPlaced(target);
986
1037
  await terminalProvider().renamePane(selectedServer(url), z.string().parse(target.pane), input.label).catch(() => undefined);
987
1038
  } });
@@ -990,7 +1041,31 @@ export function createRouteHandler(ctx) {
990
1041
  else if (url.pathname === "/v1/accounts/claude/add") {
991
1042
  if (!ownerRequest(request, data))
992
1043
  throw new BridgeError(403, "Only the owner can add a Claude account.");
993
- result = await launches.run(() => addClaudeAccount(data, selectedServer(url)));
1044
+ // `mode`: sign in a slot that exists but is signed out, or ask whether it is signed in yet.
1045
+ result = data.mode === undefined ? await launches.run(() => addClaudeAccount(data, selectedServer(url)))
1046
+ : data.mode === "sign-in-status" ? await signInClaudeAccount(data, selectedServer(url))
1047
+ : await launches.run(() => signInClaudeAccount(data, selectedServer(url)));
1048
+ }
1049
+ else if (url.pathname === "/v1/accounts/claude/settings") {
1050
+ // An account's pool and role (account-pools.ts): a field left out stays, null clears it.
1051
+ if (!ownerRequest(request, data))
1052
+ throw new BridgeError(403, "Only the owner can change an account's pool or role.");
1053
+ const input = z.object({ slug: z.string().max(64), pool: z.string().max(64).nullable().optional(), role: z.string().max(32).nullable().optional(), origin: z.unknown().optional() }).strict().parse(data);
1054
+ if (!claudeHome(input.slug))
1055
+ throw new BridgeError(404, `There is no Claude account "${input.slug}" on this computer.`);
1056
+ if (input.role !== undefined && input.role !== null && !isAccountRole(input.role))
1057
+ throw new BridgeError(400, `A role is ${ACCOUNT_ROLES.join(", ")}.`);
1058
+ const settings = await setAccountSettings(input.slug, { pool: input.pool, role: input.role })
1059
+ .catch((error) => { throw new BridgeError(400, error.message); });
1060
+ result = { ok: true, slug: input.slug, ...settings };
1061
+ }
1062
+ else if (url.pathname === "/v1/accounts/allowed-pools") {
1063
+ // The pools this computer's accounts may do work for; null clears the list (any pool).
1064
+ if (!ownerRequest(request, data))
1065
+ throw new BridgeError(403, "Only the owner can change this computer's allowed pools.");
1066
+ const input = z.object({ allowedPools: z.array(z.string().max(64)).max(64).nullable(), origin: z.unknown().optional() }).strict().parse(data);
1067
+ const allowedPools = await setComputerAllowedPools(input.allowedPools).catch((error) => { throw new BridgeError(400, error.message); });
1068
+ result = { ok: true, ...(allowedPools ? { allowedPools } : {}) };
994
1069
  }
995
1070
  else if (url.pathname === "/v1/sessions/rename") {
996
1071
  result = await renameSession(selectedServer(url), data);
@@ -1056,6 +1131,13 @@ export function createRouteHandler(ctx) {
1056
1131
  else if (url.pathname === "/v1/dispatch/workers") {
1057
1132
  result = await hookWorkers(agentHooks)(data);
1058
1133
  }
1134
+ else if (url.pathname === "/v1/dispatch/returns" && url.searchParams.get("peek") === "1") {
1135
+ // The unread returns, left unread: a watcher (`phren dispatch returns --watch`) beside an agent
1136
+ // conductor, which still takes them. Read here, never forwarded to a successor, which would take them.
1137
+ if (request.headers?.["x-phren-origin"] === "peer")
1138
+ throw new BridgeError(403, "Peer conductor operations require the authenticated generation-scoped routes.");
1139
+ result = { returns: await ctx.returns.take(false) };
1140
+ }
1059
1141
  else if (url.pathname === "/v1/dispatch/returns") {
1060
1142
  result = await conductorCall("returns", {}, data.origin, async () => ({ returns: await ctx.returns.take() }));
1061
1143
  }
@@ -1150,7 +1232,9 @@ export function createRouteHandler(ctx) {
1150
1232
  result = await launches.run(async () => enrollProject(z.object({ directory: z.string().max(4096).optional(), cloneUrl: z.string().max(512).optional(), project: z.string().max(100).optional(), store: z.string().max(200).optional() }).parse(data)));
1151
1233
  }
1152
1234
  else if (url.pathname === "/v1/simulators/action") {
1153
- result = await simulatorAct(z.string().parse(data.udid), z.object({ action: z.string(), bundleId: z.string().optional(), url: z.string().optional(), x: z.number().optional(), y: z.number().optional(), text: z.string().optional(), submit: z.boolean().optional() }).parse(data));
1235
+ result = await simulatorAct(z.string().parse(data.udid), z.object({ action: z.string(), bundleId: z.string().optional(), url: z.string().optional(), x: z.number().optional(), y: z.number().optional(),
1236
+ x1: z.number().optional(), y1: z.number().optional(), x2: z.number().optional(), y2: z.number().optional(), durationMs: z.number().optional(),
1237
+ text: z.string().optional(), submit: z.boolean().optional() }).parse(data));
1154
1238
  }
1155
1239
  else {
1156
1240
  if (url.pathname === "/v1/workspaces/launch") {
@@ -221,11 +221,13 @@ export function transcriptStreams(ctx) {
221
221
  if (deliveryFrames) {
222
222
  // Every message typed into this pane, also those sent while an
223
223
  // earlier conversation was showing there.
224
- for (const { deliveryId, state, reason } of agentHooks.deliveries.forPane(target)) {
225
- if (sentDelivery.get(deliveryId) === state)
224
+ // A delivered message is sent again once the row it landed as is known (`landed`).
225
+ for (const { deliveryId, state, reason, landed } of agentHooks.deliveries.forPane(target)) {
226
+ const key = landed ? `${state}:${landed.line}` : state;
227
+ if (sentDelivery.get(deliveryId) === key)
226
228
  continue;
227
- sentDelivery.set(deliveryId, state);
228
- send(client, { type: "delivery", ...conversation, deliveryId, state, ...(reason ? { reason } : {}) });
229
+ sentDelivery.set(deliveryId, key);
230
+ send(client, { type: "delivery", ...conversation, deliveryId, state, ...(reason ? { reason } : {}), ...(landed ? { landed } : {}) });
229
231
  }
230
232
  }
231
233
  first = false;
@@ -114,7 +114,7 @@ export async function serve(version, options = {}) {
114
114
  localComputer: { id: computerID, name: hostname() },
115
115
  forward: (origin, text, deliveryId) => succession?.forward(origin, text, deliveryId) ?? Promise.resolve(undefined),
116
116
  // Continue on another signed-in account when a Claude worker stops at its usage limit: opt-in, `phren config account-failover on`.
117
- failover: new AccountFailover({ rooms: () => dispatches.claudeRooms(), dispatch: (input, origin, continues) => succession ? succession.automatic("dispatch", { ...input, continues }, origin, () => dispatches.dispatch(input, origin, continues)) : dispatches.dispatch(input, origin, continues) }),
117
+ failover: new AccountFailover({ rooms: context => dispatches.claudeRooms(context), dispatch: (input, origin, continues) => succession ? succession.automatic("dispatch", { ...input, continues }, origin, () => dispatches.dispatch(input, origin, continues)) : dispatches.dispatch(input, origin, continues) }),
118
118
  localWorkers: hookWorkers(agentHooks),
119
119
  close: async (receipt, verifiedPeer) => {
120
120
  const data = { target: receipt.target, dispatch: receipt.moves?.slice().reverse().find(move => move.to.computer)?.id ?? receipt.id, turn: receipt.closePending.turn };
@@ -175,6 +175,7 @@ export async function serve(version, options = {}) {
175
175
  identity: (server, pane) => paneIdentity(server, pane, true),
176
176
  terminal: terminalProvider(),
177
177
  deliver: (target, text, deliveryId) => handOffs ? handOffs.enqueue({ target, text, deliveryId }) : sendPrompt(target, text, deliveryId, async () => { }),
178
+ withdraw: async (target, deliveryId, reason) => handOffs?.withdraw(deliveryId, target, reason),
178
179
  // The new agent starts in the folder an agent already ran in, so it is trusted for the new harness too.
179
180
  launch: (server, data, options) => launches.run(() => launchSession(server, data, { trustFolder: true, ...options })),
180
181
  inventory: () => launchCheckOff() ? Promise.resolve(undefined) : harnessInventoryWithin(2_500),
@@ -5,6 +5,7 @@ import { moveToSchema } from "./dispatch.js";
5
5
  import { type HarnessInventory } from "./harnesses.js";
6
6
  import { type Json, type Provider, type StartingTarget, type Target } from "./protocol.js";
7
7
  import type { TerminalProvider } from "./terminal.js";
8
+ import type { HandOffQueue } from "./hand-off-queue.js";
8
9
  export { moveToSchema };
9
10
  export type MoveTo = z.infer<typeof moveToSchema>;
10
11
  export declare const moveRequestSchema: z.ZodObject<{
@@ -48,6 +49,7 @@ export declare const moveRequestSchema: z.ZodObject<{
48
49
  continuation: z.ZodDefault<z.ZodEnum<{
49
50
  handoff: "handoff";
50
51
  resume: "resume";
52
+ "summary-by-target": "summary-by-target";
51
53
  }>>;
52
54
  id: z.ZodOptional<z.ZodString>;
53
55
  handoffTimeoutMs: z.ZodOptional<z.ZodNumber>;
@@ -110,7 +112,10 @@ declare const moveRecordSchema: z.ZodObject<{
110
112
  "new-chat": "new-chat";
111
113
  replace: "replace";
112
114
  }>>;
113
- continuation: z.ZodOptional<z.ZodLiteral<"resume">>;
115
+ continuation: z.ZodOptional<z.ZodEnum<{
116
+ resume: "resume";
117
+ "summary-by-target": "summary-by-target";
118
+ }>>;
114
119
  modeForced: z.ZodOptional<z.ZodLiteral<"conductor">>;
115
120
  handedOffTo: z.ZodOptional<z.ZodObject<{
116
121
  computer: z.ZodOptional<z.ZodString>;
@@ -247,6 +252,17 @@ export interface MovedWorker {
247
252
  to: MoveTo;
248
253
  target: Target | StartingTarget;
249
254
  }
255
+ /** What "stop and hand off now" did: interrupted the step, or why not. `idle`: the agent is on no step,
256
+ * so its request goes in without one; `typed`: the request is being or was typed; `writing`: the agent took
257
+ * it and writes its hand-off; `finished`: the move is past its hand-off, or its request can no longer be
258
+ * delivered (the move then builds a hand-off itself); `replaced`: the pane now runs another agent or
259
+ * conversation than the one the move asked, which is never interrupted for it. */
260
+ export type MoveInterrupt = {
261
+ interrupted: true;
262
+ } | {
263
+ interrupted: false;
264
+ state: "idle" | "typed" | "writing" | "finished" | "replaced";
265
+ };
250
266
  export declare function movesRoot(): string;
251
267
  /** The hand-off sits beside the new agent's brief, in a folder Claude is given read access to. */
252
268
  export declare const handoffPath: (id: string) => string;
@@ -312,6 +328,31 @@ export declare function fallbackHandoff(input: {
312
328
  dispatch?: string;
313
329
  label?: string;
314
330
  }): string;
331
+ /** Whether a Claude conversation's last turn ended on its subscription's usage limit (Claude's own
332
+ * rate-limit row): its agent cannot answer a hand-off request. */
333
+ export declare function sourceOutOfUsage(lines: readonly string[], source: Provider): boolean;
334
+ /**
335
+ * The whole conversation a summary-by-target move copies to the other computer: every prompt and reply, oldest
336
+ * first, each as it is sent (`prepare`: paths replaced, credentials redacted), within `CONVERSATION_LIMIT`.
337
+ * A longer one keeps its newest messages and says how many it left out.
338
+ */
339
+ export declare function conversationCopy(entries: readonly TailEntry[], prepare: (text: string) => string, limit?: number, complete?: boolean): string;
340
+ /**
341
+ * The hand-off for a source that does not write one (its account is out of usage, or the owner asked), for a
342
+ * fresh agent on the target computer to build itself: what happened, then as much of the conversation as fits
343
+ * in `room` characters, newest messages kept, oldest first. The target agent writes its own summary from it first.
344
+ */
345
+ export declare function targetSummaryBody(input: {
346
+ from: string;
347
+ exhausted: boolean;
348
+ entries: readonly TailEntry[];
349
+ room: number;
350
+ original?: string;
351
+ dispatch?: string;
352
+ label?: string;
353
+ /** Each message as it will be sent (paths replaced, credentials redacted), so it is measured at its sent size. */
354
+ prepare?: (text: string) => string;
355
+ }): string;
315
356
  /** The hand-off file: who moved where and when, the body, then what Phren saw. */
316
357
  export declare function handoffDocument(record: MoveRecord, body: string, observed: string, at: string, conductor?: boolean): string;
317
358
  /** The new agent's first prompt: the whole hand-off when it fits the brief, else where to read it. */
@@ -324,6 +365,8 @@ export interface MoverDeps {
324
365
  terminal: Pick<TerminalProvider, "prompt" | "sendKeys" | "processes" | "closePane">;
325
366
  /** The `hand_off` delivery path: queued while the agent is busy. */
326
367
  deliver: (target: Target, text: string, deliveryId: string) => Promise<Json>;
368
+ /** Takes back a message `deliver` queued while it is still untyped (`HandOffQueue.withdraw`). */
369
+ withdraw?: (target: Target, deliveryId: string, reason: string) => Promise<unknown>;
327
370
  /** Starts the new agent (`startSession`), in `into` when given. */
328
371
  launch: (server: string, data: Json, options: {
329
372
  into?: {
@@ -337,6 +380,11 @@ export interface MoverDeps {
337
380
  inventory: () => Promise<HarnessInventory | undefined>;
338
381
  /** The conversation's transcript lines, its tail is enough. */
339
382
  transcript: (target: Target) => Promise<string[]>;
383
+ /** The whole transcript for a summary-by-target move's copy, and whether all of it was read. */
384
+ conversation?: (target: Target) => Promise<{
385
+ lines: string[];
386
+ complete: boolean;
387
+ }>;
340
388
  /** Copies a Claude conversation into another account's home (`copyClaudeConversation` over its transcript).
341
389
  * With `check`, only resolves and validates both ends, so a move is refused before the old agent exits. */
342
390
  copyConversation?: (target: Target, to: ClaudeHome, check?: boolean) => Promise<string>;
@@ -366,9 +414,17 @@ export interface MoverDeps {
366
414
  export declare class SessionMover {
367
415
  private readonly deps;
368
416
  private readonly cancelled;
417
+ /** Moves this process is waiting on: their hand-off request was handed to the queue, and the wait for the
418
+ * agent's answer is not over (it answered, the wait ran out, or the owner aborted). Only these are interrupted:
419
+ * a move whose request was never sent (summary-by-target, or not yet), or one this process no longer runs
420
+ * (the Hook restarted), has no request an Escape would let in. */
421
+ private readonly asking;
422
+ /** Per move, the hand-off's end and an interrupt's check-and-send, one at a time. */
423
+ private readonly lifecycles;
369
424
  private readonly admissions;
370
425
  private readonly running;
371
426
  constructor(deps: MoverDeps);
427
+ private lifecycle;
372
428
  private get now();
373
429
  private sleep;
374
430
  private get poll();
@@ -381,7 +437,20 @@ export declare class SessionMover {
381
437
  settled(server: string, pane: string): Promise<void> | undefined;
382
438
  private update;
383
439
  private run;
440
+ /**
441
+ * "Stop <agent> and hand off now": Escape to the old agent only while the move's hand-off request is
442
+ * still held for it (queued behind the step it is on, not yet typed), so the step stops and the request
443
+ * goes in, and never into the hand-off the agent is writing. Checked and sent under the hand-off queue's
444
+ * lock (`whileQueued`), which is what types the request, and under the move's own lifecycle lock, which is
445
+ * what ends the hand-off wait: the move cannot go on to exit or launch between the check and the key.
446
+ * `state` says why it did not: the request is being or was typed (`typed`), the agent is writing its
447
+ * hand-off (`writing`), the move is past it, or the pane runs another agent now (`replaced`).
448
+ */
449
+ interrupt(id: string, queue?: Pick<HandOffQueue, "whileQueued">, escape?: (target: Target) => Promise<void>): Promise<MoveInterrupt>;
384
450
  abort(id: string): Promise<MoveRecord>;
451
+ /** Takes the move's hand-off request back while it is still queued. Outside the move's lifecycle lock: an
452
+ * interrupt holds the queue's lock while it waits for that one, so this must not wait the other way round. */
453
+ private withdrawRequest;
385
454
  private assertNotAborted;
386
455
  private continueOnPeer;
387
456
  /** Startup and tick recovery reuse the receiving Hook's durable move id.