owenloop 0.4.0 → 0.5.0

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 (155) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +98 -25
  3. package/bin/owenloop.mjs +2 -2
  4. package/dist/packages/work/src/agent/brief.d.ts +172 -0
  5. package/dist/packages/work/src/agent/brief.js +193 -0
  6. package/dist/packages/work/src/agent/loop.d.ts +135 -0
  7. package/dist/packages/work/src/agent/loop.js +542 -0
  8. package/dist/packages/work/src/agent/workdir.d.ts +210 -0
  9. package/dist/packages/work/src/agent/workdir.js +319 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +90 -0
  11. package/dist/packages/work/src/bundle/cache.js +324 -0
  12. package/dist/packages/work/src/bundle/fetch.d.ts +85 -0
  13. package/dist/packages/work/src/bundle/fetch.js +325 -0
  14. package/dist/packages/work/src/bundle/types.d.ts +160 -0
  15. package/dist/packages/work/src/bundle/types.js +1 -0
  16. package/dist/packages/work/src/credentials/owenloop.d.ts +11 -0
  17. package/dist/packages/work/src/credentials/owenloop.js +28 -0
  18. package/dist/packages/work/src/credentials/reader.d.ts +36 -0
  19. package/dist/packages/work/src/credentials/reader.js +32 -0
  20. package/dist/packages/work/src/credentials/resolve.d.ts +19 -0
  21. package/dist/packages/work/src/credentials/resolve.js +56 -0
  22. package/dist/packages/work/src/exec/loop.d.ts +29 -0
  23. package/dist/packages/work/src/exec/loop.js +215 -0
  24. package/dist/packages/work/src/exec/receipt.d.ts +38 -0
  25. package/dist/packages/work/src/exec/receipt.js +21 -0
  26. package/dist/packages/work/src/exec/runner.d.ts +65 -0
  27. package/dist/packages/work/src/exec/runner.js +185 -0
  28. package/dist/packages/work/src/harness/child-env.d.ts +100 -0
  29. package/dist/packages/work/src/harness/child-env.js +127 -0
  30. package/dist/packages/work/src/harness/claude.d.ts +128 -0
  31. package/dist/packages/work/src/harness/claude.js +635 -0
  32. package/dist/packages/work/src/harness/codex.d.ts +110 -0
  33. package/dist/packages/work/src/harness/codex.js +896 -0
  34. package/dist/packages/work/src/harness/contract.d.ts +283 -0
  35. package/dist/packages/work/src/harness/contract.js +32 -0
  36. package/dist/packages/work/src/harness/fake.d.ts +59 -0
  37. package/dist/packages/work/src/harness/fake.js +90 -0
  38. package/dist/packages/work/src/harness/jsonrpc-stdio.d.ts +108 -0
  39. package/dist/packages/work/src/harness/jsonrpc-stdio.js +344 -0
  40. package/dist/packages/work/src/harness/permissions.d.ts +62 -0
  41. package/dist/packages/work/src/harness/permissions.js +93 -0
  42. package/dist/packages/work/src/harness/registry.d.ts +47 -0
  43. package/dist/packages/work/src/harness/registry.js +45 -0
  44. package/dist/packages/work/src/harness/session-store.d.ts +163 -0
  45. package/dist/packages/work/src/harness/session-store.js +319 -0
  46. package/dist/packages/work/src/harness/types.d.ts +29 -0
  47. package/dist/packages/work/src/harness/types.js +14 -0
  48. package/dist/packages/work/src/harnesses.d.ts +38 -0
  49. package/dist/packages/work/src/harnesses.js +38 -0
  50. package/dist/packages/work/src/hold/loop.d.ts +36 -0
  51. package/dist/packages/work/src/hold/loop.js +23 -0
  52. package/dist/packages/work/src/hold/mcp.d.ts +55 -0
  53. package/dist/packages/work/src/hold/mcp.js +149 -0
  54. package/dist/packages/work/src/hub/client.d.ts +22 -0
  55. package/dist/packages/work/src/hub/client.js +78 -0
  56. package/dist/packages/work/src/hub/types.d.ts +290 -0
  57. package/dist/packages/work/src/hub/types.js +28 -0
  58. package/dist/packages/work/src/lease/loop.d.ts +94 -0
  59. package/dist/packages/work/src/lease/loop.js +277 -0
  60. package/dist/packages/work/src/main.d.ts +1 -0
  61. package/dist/packages/work/src/main.js +48 -0
  62. package/dist/packages/work/src/mcp/server.d.ts +125 -0
  63. package/dist/packages/work/src/mcp/server.js +320 -0
  64. package/dist/packages/work/src/roles/agent-run.d.ts +118 -0
  65. package/dist/packages/work/src/roles/agent-run.js +447 -0
  66. package/dist/packages/work/src/roles/exec.d.ts +40 -0
  67. package/dist/packages/work/src/roles/exec.js +203 -0
  68. package/dist/packages/work/src/roles/hold.d.ts +68 -0
  69. package/dist/packages/work/src/roles/hold.js +324 -0
  70. package/dist/packages/work/src/roles/join.d.ts +18 -0
  71. package/dist/packages/work/src/roles/join.js +204 -0
  72. package/dist/packages/work/src/roles/lint.d.ts +59 -0
  73. package/dist/packages/work/src/roles/lint.js +200 -0
  74. package/dist/packages/work/src/roles/prepare.d.ts +1 -0
  75. package/dist/packages/work/src/roles/prepare.js +249 -0
  76. package/dist/packages/work/src/roles/release.d.ts +48 -0
  77. package/dist/packages/work/src/roles/release.js +137 -0
  78. package/dist/packages/work/src/roles/sessions.d.ts +61 -0
  79. package/dist/packages/work/src/roles/sessions.js +180 -0
  80. package/dist/packages/work/src/roles/settings.d.ts +6 -0
  81. package/dist/packages/work/src/roles/settings.js +66 -0
  82. package/dist/packages/work/src/roles/shift.d.ts +12 -0
  83. package/dist/packages/work/src/roles/shift.js +228 -0
  84. package/dist/packages/work/src/roles/signals.d.ts +55 -0
  85. package/dist/packages/work/src/roles/signals.js +62 -0
  86. package/dist/packages/work/src/settings/provision.d.ts +21 -0
  87. package/dist/packages/work/src/settings/provision.js +47 -0
  88. package/dist/packages/work/src/settings/settings.d.ts +120 -0
  89. package/dist/packages/work/src/settings/settings.js +116 -0
  90. package/dist/packages/work/src/shift/client.d.ts +24 -0
  91. package/dist/packages/work/src/shift/client.js +124 -0
  92. package/dist/packages/work/src/shift/loop.d.ts +120 -0
  93. package/dist/packages/work/src/shift/loop.js +468 -0
  94. package/dist/packages/work/src/shift/protocol.d.ts +91 -0
  95. package/dist/packages/work/src/shift/protocol.js +24 -0
  96. package/dist/packages/work/src/shift/routing.d.ts +35 -0
  97. package/dist/packages/work/src/shift/routing.js +50 -0
  98. package/dist/packages/work/src/shift/runtime.d.ts +43 -0
  99. package/dist/packages/work/src/shift/runtime.js +274 -0
  100. package/dist/packages/work/src/shift/server.d.ts +23 -0
  101. package/dist/packages/work/src/shift/server.js +716 -0
  102. package/dist/packages/work/src/shift/spawn.d.ts +86 -0
  103. package/dist/packages/work/src/shift/spawn.js +100 -0
  104. package/dist/packages/work/src/shift/state.d.ts +77 -0
  105. package/dist/packages/work/src/shift/state.js +162 -0
  106. package/dist/packages/work/src/usage.d.ts +6 -0
  107. package/dist/packages/work/src/usage.js +175 -0
  108. package/dist/{add.d.ts → src/add.d.ts} +12 -40
  109. package/dist/{add.js → src/add.js} +11 -176
  110. package/dist/src/cli.d.ts +147 -0
  111. package/dist/{cli.js → src/cli.js} +1643 -353
  112. package/dist/src/credentials.d.ts +280 -0
  113. package/dist/src/credentials.js +697 -0
  114. package/dist/{defs.js → src/defs.js} +59 -36
  115. package/dist/{engine.d.ts → src/engine.d.ts} +8 -8
  116. package/dist/{engine.js → src/engine.js} +29 -20
  117. package/dist/{hub.d.ts → src/hub.d.ts} +330 -2
  118. package/dist/{hub.js → src/hub.js} +531 -1
  119. package/dist/{index.d.ts → src/index.d.ts} +3 -1
  120. package/dist/{index.js → src/index.js} +2 -1
  121. package/dist/src/lock.d.ts +80 -0
  122. package/dist/src/lock.js +217 -0
  123. package/dist/src/mcp/serve.d.ts +85 -0
  124. package/dist/src/mcp/serve.js +702 -0
  125. package/dist/src/mcp/server.d.ts +132 -0
  126. package/dist/src/mcp/server.js +327 -0
  127. package/dist/{model.d.ts → src/model.d.ts} +59 -4
  128. package/dist/{model.js → src/model.js} +149 -22
  129. package/dist/{types.d.ts → src/types.d.ts} +66 -24
  130. package/dist/{util.d.ts → src/util.d.ts} +25 -0
  131. package/dist/{util.js → src/util.js} +26 -0
  132. package/dist/src/work-settings.d.ts +57 -0
  133. package/dist/src/work-settings.js +84 -0
  134. package/docs/authoring.md +102 -53
  135. package/docs/cli.md +883 -29
  136. package/docs/design.md +119 -45
  137. package/docs/embedding.md +39 -14
  138. package/examples/workflows/{command-worker.yaml → command-executor.yaml} +15 -15
  139. package/examples/workflows/compile-dev-playbook.yaml +338 -0
  140. package/examples/workflows/judges/gate-sharpness.md +39 -0
  141. package/examples/workflows/judges/security.md +34 -0
  142. package/package.json +17 -8
  143. package/dist/cli.d.ts +0 -83
  144. /package/dist/{defs.d.ts → src/defs.d.ts} +0 -0
  145. /package/dist/{factory.d.ts → src/factory.d.ts} +0 -0
  146. /package/dist/{factory.js → src/factory.js} +0 -0
  147. /package/dist/{paths.d.ts → src/paths.d.ts} +0 -0
  148. /package/dist/{paths.js → src/paths.js} +0 -0
  149. /package/dist/{schema.d.ts → src/schema.d.ts} +0 -0
  150. /package/dist/{schema.js → src/schema.js} +0 -0
  151. /package/dist/{store.d.ts → src/store.d.ts} +0 -0
  152. /package/dist/{store.js → src/store.js} +0 -0
  153. /package/dist/{types.js → src/types.js} +0 -0
  154. /package/dist/{untar.d.ts → src/untar.d.ts} +0 -0
  155. /package/dist/{untar.js → src/untar.js} +0 -0
@@ -0,0 +1,280 @@
1
+ /**
2
+ * Credential WRITE + OAuth refresh library surface.
3
+ *
4
+ * Extracted from `src/cli.ts` (where these were module-private) so external
5
+ * consumers — a future `owenloop mcp` stdio server, an `owenloop work join` command —
6
+ * can store credentials and keep an OAuth access token fresh without depending
7
+ * on the CLI module. The exported `storeCredential` / `deleteCredential` /
8
+ * `ensureFreshOAuth` are re-imported by `cli.ts`, so every existing subcommand
9
+ * keeps its exact behavior.
10
+ *
11
+ * **Concurrency safety (the reason this module exists):** the refresh-and-persist
12
+ * critical section is serialized by a lockfile next to the store
13
+ * (`~/.config/owenloop/credentials.lock`, via `src/lock.ts`). Multiple long-lived
14
+ * processes sharing one slot (the `mcp` server case) would otherwise race a
15
+ * refresh — both read the old refresh token, both rotate it server-side, and the
16
+ * loser persists a now-dead token, causing a silent logout an hour later. The
17
+ * lock turns "two refreshes race" into "the second process adopts the first's
18
+ * result": acquire → re-read the slot → adopt-or-refresh → persist → release.
19
+ *
20
+ * This module imports ONLY `hub.ts` (store internals), `util.ts` (`CliError`,
21
+ * `nowMs`), and `lock.ts` (node-builtin-only) — never `cli.ts`. That keeps the
22
+ * package barrel (`src/index.ts`) free of the CLI/add/untar runtime closure and
23
+ * avoids an import cycle.
24
+ */
25
+ import type { Credential, CredentialSlotSelector, Keychain } from './hub.ts';
26
+ /**
27
+ * The dependencies the credential surface needs — a strict subset of the CLI's
28
+ * `CliIO`, which structurally satisfies this interface, so every `cli.ts` call
29
+ * site keeps passing its `io` unchanged. A library consumer constructs just
30
+ * `{ env: process.env }` (plus an optional keychain/fetch) without faking the
31
+ * CLI's `out`/`err`/`cwd`.
32
+ */
33
+ export interface CredentialIO {
34
+ env: Record<string, string | undefined>;
35
+ /**
36
+ * OS keychain backend for credential storage. `undefined` — non-mac, or
37
+ * `OWENLOOP_NO_KEYCHAIN=1` — selects the file backend. A keychain write
38
+ * failure is a hard error, never a silent file fallback (REL-6).
39
+ */
40
+ keychain?: Keychain;
41
+ /** Injectable for hermetic tests — the OAuth-refresh network calls use this. */
42
+ fetch?: typeof globalThis.fetch;
43
+ }
44
+ /**
45
+ * Store a credential for `origin` in `slot`, in the chosen backend ONLY;
46
+ * returns which one. Serialized by the credential lock so a plain write from
47
+ * `login` / `agent new` can never interleave with a refresh-and-persist.
48
+ *
49
+ * The external-command refusal runs BEFORE acquiring the lock: in that mode the
50
+ * command (not the local store) is authoritative, so a write is refused with no
51
+ * lockfile/config-dir side effect at all.
52
+ *
53
+ * Async because gaining the lock made it so — acceptable because this function
54
+ * was module-private before this change; the NEW public API is born async.
55
+ */
56
+ export declare function storeCredential(io: CredentialIO, origin: string, slot: CredentialSlotSelector, cred: Credential): Promise<'keychain' | 'file'>;
57
+ /**
58
+ * Delete the stored credential for `(origin, slot)` from BOTH backends, under
59
+ * the credential lock so a logout can never interleave with a concurrent
60
+ * refresh-and-persist. Returns whether anything was removed. Async for the same
61
+ * born-with-the-lock reason as `storeCredential`.
62
+ */
63
+ export declare function deleteCredential(io: CredentialIO, origin: string, slot: CredentialSlotSelector): Promise<boolean>;
64
+ /** The Bearer value for an authenticated request. Never logged. */
65
+ export declare function authHeader(cred: Credential): string;
66
+ export declare function hubMaxResponseBytes(io: CredentialIO): number;
67
+ /**
68
+ * Read a `Response` body into memory with a hard byte cap, streaming so an
69
+ * oversized body is rejected without first buffering the whole thing. Also used
70
+ * by the `add` tarball/sha fetches in `cli.ts` (which import it back), hence the
71
+ * `export`. `label` names the request in the error and is origin+path or
72
+ * `owner/repo@sha` only — never a token. Counting post-decode bytes (what lands
73
+ * in memory) is deliberate: the cap protects memory, not wire bytes.
74
+ *
75
+ * `res.body === null` (empty/no-body response) yields empty bytes, so callers
76
+ * behave exactly as they did under `arrayBuffer()`. An absent, malformed, or
77
+ * multi-valued `Content-Length` skips the header check — the counting path is
78
+ * the real guard (GitHub codeload tarballs are typically chunked, no header). A
79
+ * `TimeoutError`/`AbortError` from `read()` (the abort signal fired mid-body)
80
+ * propagates untouched, so each call site's existing timeout mapping still
81
+ * fires exactly as it did for `arrayBuffer()` rejections. `cancel()` may reject
82
+ * on an already-errored stream — swallowed; the cap `CliError` is the story.
83
+ */
84
+ export declare function readBodyBounded(res: Response, cap: number, label: string): Promise<Uint8Array>;
85
+ /**
86
+ * `fetch` wrapper putting a deadline on every hub/auth call (REL-7). The abort
87
+ * signal is threaded into `fetch` AND the body is read (via `readBodyBounded`,
88
+ * which caps the response size — see HUB_MAX_RESPONSE_BYTES) inside the same
89
+ * try, so the deadline covers a stalled BODY read too — the exact undici
90
+ * behavior the two `add` fetches document (`AbortSignal.timeout` ties the
91
+ * signal to the body stream). The returned `Response` re-exposes the read
92
+ * body, so every call site's `res.json()` / `res.status` /
93
+ * `res.headers.get(...)` usage is byte-for-byte unchanged. A
94
+ * `TimeoutError`/`AbortError` becomes a clear `CliError` (naming the request,
95
+ * which is origin+path only — never a token); anything else is rethrown
96
+ * untouched.
97
+ *
98
+ * `redirect: 'error'` is forced on every call — after the `...init` spread, so
99
+ * no caller can override it — to close the redirect gap `resolveEndpoint`
100
+ * (SEC-4) cannot see: same-origin validation covers only the INITIAL URL, but a
101
+ * validated endpoint answering 307/308 would re-send the POST body (refresh
102
+ * token, PKCE verifier, auth code, workflow YAML) to a foreign origin — undici
103
+ * strips the Authorization header on a cross-origin redirect but RESENDS the
104
+ * body. The hub protocol has no redirects, so any 3xx is a hard, loud failure
105
+ * mapped to a `CliError` (again naming origin+path only, never a token).
106
+ */
107
+ export declare function hubFetch(io: CredentialIO, url: string, init?: RequestInit): Promise<Response>;
108
+ interface AsMetadata {
109
+ authorization_endpoint?: string;
110
+ token_endpoint?: string;
111
+ registration_endpoint?: string;
112
+ }
113
+ export declare function discoverMetadata(io: CredentialIO, origin: string): Promise<AsMetadata>;
114
+ export declare function discoverTokenEndpoint(io: CredentialIO, origin: string): Promise<string>;
115
+ /**
116
+ * Ensure an `oauth` credential's access token is fresh: if it expires within
117
+ * 60s, refresh once (grant_type=refresh_token) and persist the new token. No-op
118
+ * for `agent`/`oauth-pasted` credentials (they don't refresh). Returns the
119
+ * possibly-updated credential.
120
+ *
121
+ * The `expiresAt - nowMs() > FRESH_WINDOW_MS` fast path is the cheap first check
122
+ * of a double-checked pattern: it returns WITHOUT locking; the re-read under the
123
+ * lock inside `refreshOAuth` is the second check.
124
+ *
125
+ * `slot` is the slot the credential was READ from — a refreshed token must be
126
+ * written back to that same slot, never to a default one.
127
+ */
128
+ export declare function ensureFreshOAuth(io: CredentialIO, origin: string, slot: CredentialSlotSelector, cred: Credential, persist?: boolean): Promise<Credential>;
129
+ /**
130
+ * Refresh an `oauth` credential's access token.
131
+ *
132
+ * `persist` defaults to true — the normal case is refreshing an ALREADY stored,
133
+ * trusted credential (push/connect), where persisting immediately matters
134
+ * because refresh tokens can be single-use/rotating: losing the new one to a
135
+ * later crash would strand the user. `verifyCredential`'s login-time use passes
136
+ * `persist: false` — a not-yet-stored credential must never be written to
137
+ * disk/keychain before it is proven to work end to end.
138
+ *
139
+ * Two paths:
140
+ *
141
+ * - **Unlocked** (`persist: false`, i.e. login-time verify; OR an external
142
+ * credential command is configured): byte-for-byte the pre-lock behavior —
143
+ * refresh over HTTP, do NOT touch the store, do NOT lock, do NOT adopt.
144
+ * `persist: false` must never adopt a stored credential: the caller is
145
+ * verifying a specific not-yet-stored token, and handing back some other slot
146
+ * occupant would verify the WRONG credential. In external-command mode
147
+ * owenloop owns none of the credential lifecycle, so it neither locks nor
148
+ * persists (matching the old `persist && externalCredentialCommand ===
149
+ * undefined` gate).
150
+ *
151
+ * - **Locked** (`persist: true` and no external command): acquire the credential
152
+ * lock, RE-READ the slot, then decide:
153
+ * * stored is oauth AND its accessToken differs from ours AND it is fresh
154
+ * (> `FRESH_WINDOW_MS` from expiry) → another process already refreshed;
155
+ * adopt its credential with ZERO network calls and ZERO writes.
156
+ * * stored is oauth AND differs from ours but is NOT fresh → refresh using
157
+ * STORED as input (its refreshToken is the newest link in the rotation
158
+ * chain; ours is provably older), persist, return.
159
+ * * otherwise (stored same token, absent, or non-oauth) → refresh using
160
+ * `cred`, persist, return.
161
+ * Release the lock in `finally`.
162
+ *
163
+ * The `accessToken !== cred.accessToken` guard (not freshness alone) exists
164
+ * because `authedGet` calls this on a 401 with a token that may not be near
165
+ * expiry: freshness-only adoption would hand the caller back its own
166
+ * just-rejected token and turn a recoverable 401 into a hard failure.
167
+ * Token-differs ⇒ someone else moved the chain; token-same ⇒ we are first,
168
+ * refresh for real. The locked-section persist calls `storeCredentialUnlocked`
169
+ * (not the exported wrapper) — it already holds the lock.
170
+ */
171
+ export declare function refreshOAuth(io: CredentialIO, origin: string, slot: CredentialSlotSelector, cred: Extract<Credential, {
172
+ kind: 'oauth';
173
+ }>, persist?: boolean): Promise<Credential>;
174
+ /**
175
+ * The result of `mintAgentCredential`. Deliberately carries NO token field —
176
+ * only non-secret handles the caller may print. The minted `olp_` plaintext is
177
+ * written to the credential store inside `mintAgentCredential` and never leaves
178
+ * it, so no caller can leak what it never received (§6 "rule of gates").
179
+ */
180
+ export interface MintAgentResult {
181
+ /** Token id — a non-secret revocation handle. */
182
+ id: string;
183
+ /** The minted agent's id — a non-secret handle. */
184
+ agentId: string;
185
+ /** Resolved crew NAMES from the server. */
186
+ crews: string[];
187
+ /**
188
+ * The minted token's scopes — the client-resolved request value (the H3 route
189
+ * requires non-empty scopes and honors them verbatim, so request == minted).
190
+ * Non-secret; lets callers print the truth instead of a hard-coded literal.
191
+ */
192
+ scopes: string[];
193
+ /** Which local backend the token landed in. */
194
+ storage: 'keychain' | 'file';
195
+ }
196
+ /**
197
+ * Mint a new Scoped Identity on `origin` as the human `cred` and persist the
198
+ * returned `olp_` token to slot `agent:<name>`. CLI-free (no `Args`, no exit
199
+ * codes — the caller maps failures to exit codes) so both `owenloop agent new`
200
+ * (O3) and `owenloop mcp`'s `create_agent` (O2) can reuse it.
201
+ *
202
+ * **The token NEVER leaves this function.** It flows exactly one hop —
203
+ * `asMintAgentTokenOk(body).token` → `storeCredential` — and is never returned,
204
+ * thrown, logged, or embedded in any message (identity model §6). The returned
205
+ * `MintAgentResult` structurally omits it. The hub's 4xx `message` (e.g. H1's
206
+ * `agent name already taken: "…"`) is surfaced verbatim via `CliError`; a
207
+ * malformed 2xx names the offending FIELD only, never a value.
208
+ *
209
+ * Order is load-bearing (PR #69 lesson): the client-side name check and the
210
+ * external-command refusal both run BEFORE any network call. Refusing only at
211
+ * `storeCredential` time would mint a server-side token that can never be stored
212
+ * locally — permanently burning the agent name (re-running refuses "taken").
213
+ *
214
+ * @param humanSlot the slot `cred` was read from (always `{principal:'human'}`
215
+ * today; explicit for symmetry with the store/refresh signatures).
216
+ * @param params.scopes defaults to `['work']` — the H3 route REQUIRES a
217
+ * non-empty `scopes`; an empty list is server-refused.
218
+ * @param params.crews omitted when absent so the server defaults to the minter's
219
+ * personal crew (`crews: []` is server-refused with `crew_invalid`).
220
+ */
221
+ export declare function mintAgentCredential(io: CredentialIO, origin: string, humanSlot: CredentialSlotSelector, cred: Credential, params: {
222
+ name: string;
223
+ crews?: string[];
224
+ scopes?: string[];
225
+ }): Promise<MintAgentResult>;
226
+ /**
227
+ * The result of `rekeyAgentCredential`. Like `MintAgentResult`, carries NO token
228
+ * field — only non-secret handles the caller may print. The new `olp_` plaintext
229
+ * is written to the store inside `rekeyAgentCredential` and never leaves it.
230
+ *
231
+ * `revokedTokenIds` are the ids the rekey invalidated server-side — the OLD
232
+ * installation's credential(s). Their presence is the honest signal that any
233
+ * still-running copy of this agent elsewhere is now disconnected. No `crews`
234
+ * field: rekey changes no crew membership.
235
+ */
236
+ export interface RekeyAgentResult {
237
+ /** New token id — a non-secret revocation handle. */
238
+ id: string;
239
+ /** The rekeyed agent's id — a non-secret handle. */
240
+ agentId: string;
241
+ /** Ids of the tokens this rekey revoked (the old installation's). */
242
+ revokedTokenIds: string[];
243
+ /** The new token's scopes. */
244
+ scopes: string[];
245
+ /** Which local backend the new token landed in. */
246
+ storage: 'keychain' | 'file';
247
+ }
248
+ /**
249
+ * Re-key an EXISTING Scoped Identity on `origin` as the human `cred`: the hub
250
+ * mints a fresh `olp_` token for `agentId`, REVOKES the identity's current
251
+ * token(s), and this function persists the new token into the SAME
252
+ * `agent:<name>` slot — overwriting the old one. Sibling of
253
+ * `mintAgentCredential` with the identical §6 discipline; the only shape
254
+ * differences are the endpoint (`/api/rekey_agent_token`), the request body
255
+ * (`{agentId}` — no name/scopes/crews; rekey preserves crews), and the response
256
+ * guard (`asRekeyAgentTokenOk` — no `crews` field).
257
+ *
258
+ * **The token NEVER leaves this function.** It flows exactly one hop —
259
+ * `asRekeyAgentTokenOk(body).token` → `storeCredential` — and is never returned,
260
+ * thrown, logged, or embedded in any message. The returned `RekeyAgentResult`
261
+ * structurally omits it.
262
+ *
263
+ * **Irreversibility (why the caller must gate this behind a hard auth step):**
264
+ * a successful rekey has ALREADY revoked the old token server-side by the time
265
+ * this function returns. If the local `storeCredential` then fails, the old
266
+ * installation is disconnected AND the new token is unrecoverable locally — the
267
+ * error says exactly that and points at console Reconnect; it never prints the
268
+ * token as a fallback.
269
+ *
270
+ * @param humanSlot the slot `cred` was read from (always `{principal:'human'}`).
271
+ * @param params.agentId the identity to rekey (resolved by the caller from the
272
+ * `agent_identities` listing by NAME — names are org-unique).
273
+ * @param params.name the agent account name — the local slot `agent:<name>` the
274
+ * new token is written to. Validated before any I/O.
275
+ */
276
+ export declare function rekeyAgentCredential(io: CredentialIO, origin: string, humanSlot: CredentialSlotSelector, cred: Credential, params: {
277
+ agentId: string;
278
+ name: string;
279
+ }): Promise<RekeyAgentResult>;
280
+ export {};