@ckanner/flywheel 0.32.0 → 0.33.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 (134) hide show
  1. package/CHANGELOG.md +17 -1
  2. package/README.md +11 -2
  3. package/README.zh-CN.md +6 -1
  4. package/THIRD_PARTY_NOTICES.md +42 -0
  5. package/bin/runtime.js +25 -31
  6. package/cordis.patch.yml +5 -0
  7. package/dist/bridge.mjs +421 -0
  8. package/dist/claude-code-pro-bridge.mjs +82 -0
  9. package/dist/claude-code-pro-worker.mjs +5 -0
  10. package/dist/client.js +4078 -0
  11. package/dist/codex-pro-bridge.mjs +75 -0
  12. package/dist/codex-pro-worker.mjs +5 -0
  13. package/dist/console-read.mjs +51 -0
  14. package/dist/control.mjs +218 -0
  15. package/dist/index.mjs +185 -0
  16. package/dist/installation.mjs +56 -0
  17. package/dist/machine-worker.mjs +241 -0
  18. package/dist/policy.mjs +91 -0
  19. package/dist/prewarm.mjs +136 -0
  20. package/dist/protocol.mjs +260 -0
  21. package/dist/task-association.mjs +127 -0
  22. package/dist/worker.mjs +52 -0
  23. package/dist/workspaces.mjs +42 -0
  24. package/docs/README.md +1 -1
  25. package/docs/README.zh-CN.md +1 -1
  26. package/docs/design.md +8 -5
  27. package/docs/en/configuration.md +1 -1
  28. package/docs/en/contributing.md +5 -6
  29. package/docs/en/flow-console.md +1 -1
  30. package/docs/en/getting-started.md +13 -3
  31. package/docs/en/releasing.md +132 -174
  32. package/docs/validation/2026-11-13-release-0.32.0.md +78 -0
  33. package/docs/validation/2026-11-13-release-0.32.1.md +83 -0
  34. package/docs/validation/2026-11-14-single-package.md +60 -0
  35. package/docs/validation/README.md +3 -0
  36. package/docs/zh-CN/configuration.md +1 -1
  37. package/docs/zh-CN/contributing.md +4 -5
  38. package/docs/zh-CN/flow-console.md +1 -1
  39. package/docs/zh-CN/getting-started.md +10 -4
  40. package/docs/zh-CN/releasing.md +97 -81
  41. package/native/darwin-amd64/flywheel +0 -0
  42. package/native/darwin-arm64/flywheel +0 -0
  43. package/native/linux-amd64/flywheel +0 -0
  44. package/native/linux-arm64/flywheel +0 -0
  45. package/native/manifest.json +22 -0
  46. package/node_modules/dsh-subagent-codex-pro/CHANGELOG.md +403 -0
  47. package/node_modules/dsh-subagent-codex-pro/LICENSE +21 -0
  48. package/node_modules/dsh-subagent-codex-pro/README.md +557 -0
  49. package/node_modules/dsh-subagent-codex-pro/cordis.patch.yml +30 -0
  50. package/node_modules/dsh-subagent-codex-pro/docs/README.zh.md +355 -0
  51. package/node_modules/dsh-subagent-codex-pro/docs/machine-lifecycle-validation.md +65 -0
  52. package/node_modules/dsh-subagent-codex-pro/docs/machine-lifecycle.md +144 -0
  53. package/node_modules/dsh-subagent-codex-pro/docs/machine-lifecycle.zh.md +98 -0
  54. package/node_modules/dsh-subagent-codex-pro/docs/machine.md +194 -0
  55. package/node_modules/dsh-subagent-codex-pro/docs/orchestration.zh.md +86 -0
  56. package/node_modules/dsh-subagent-codex-pro/lib/codex-exec.js +68 -0
  57. package/node_modules/dsh-subagent-codex-pro/lib/codex-exec.js.map +1 -0
  58. package/node_modules/dsh-subagent-codex-pro/lib/dsh-types.js +15 -0
  59. package/node_modules/dsh-subagent-codex-pro/lib/dsh-types.js.map +1 -0
  60. package/node_modules/dsh-subagent-codex-pro/lib/index.js +830 -0
  61. package/node_modules/dsh-subagent-codex-pro/lib/index.js.map +1 -0
  62. package/node_modules/dsh-subagent-codex-pro/lib/jobs.js +35 -0
  63. package/node_modules/dsh-subagent-codex-pro/lib/jobs.js.map +1 -0
  64. package/node_modules/dsh-subagent-codex-pro/lib/jsonrpc.js +229 -0
  65. package/node_modules/dsh-subagent-codex-pro/lib/jsonrpc.js.map +1 -0
  66. package/node_modules/dsh-subagent-codex-pro/lib/machine-cli.js +101 -0
  67. package/node_modules/dsh-subagent-codex-pro/lib/machine-cli.js.map +1 -0
  68. package/node_modules/dsh-subagent-codex-pro/lib/machine-local.js +122 -0
  69. package/node_modules/dsh-subagent-codex-pro/lib/machine-local.js.map +1 -0
  70. package/node_modules/dsh-subagent-codex-pro/lib/machine-recovery.js +167 -0
  71. package/node_modules/dsh-subagent-codex-pro/lib/machine-recovery.js.map +1 -0
  72. package/node_modules/dsh-subagent-codex-pro/lib/machine-supervision.js +141 -0
  73. package/node_modules/dsh-subagent-codex-pro/lib/machine-supervision.js.map +1 -0
  74. package/node_modules/dsh-subagent-codex-pro/lib/machine-supervisor.js +128 -0
  75. package/node_modules/dsh-subagent-codex-pro/lib/machine-supervisor.js.map +1 -0
  76. package/node_modules/dsh-subagent-codex-pro/lib/machine.js +104 -0
  77. package/node_modules/dsh-subagent-codex-pro/lib/machine.js.map +1 -0
  78. package/node_modules/dsh-subagent-codex-pro/lib/process-guardian.js +156 -0
  79. package/node_modules/dsh-subagent-codex-pro/lib/process-guardian.js.map +1 -0
  80. package/node_modules/dsh-subagent-codex-pro/lib/run.js +842 -0
  81. package/node_modules/dsh-subagent-codex-pro/lib/run.js.map +1 -0
  82. package/node_modules/dsh-subagent-codex-pro/lib/structured.js +329 -0
  83. package/node_modules/dsh-subagent-codex-pro/lib/structured.js.map +1 -0
  84. package/node_modules/dsh-subagent-codex-pro/lib/tool.js +295 -0
  85. package/node_modules/dsh-subagent-codex-pro/lib/tool.js.map +1 -0
  86. package/node_modules/dsh-subagent-codex-pro/lib/types/codex-exec.d.ts +88 -0
  87. package/node_modules/dsh-subagent-codex-pro/lib/types/codex-exec.d.ts.map +1 -0
  88. package/node_modules/dsh-subagent-codex-pro/lib/types/dsh-types.d.ts +179 -0
  89. package/node_modules/dsh-subagent-codex-pro/lib/types/dsh-types.d.ts.map +1 -0
  90. package/node_modules/dsh-subagent-codex-pro/lib/types/index.d.ts +266 -0
  91. package/node_modules/dsh-subagent-codex-pro/lib/types/index.d.ts.map +1 -0
  92. package/node_modules/dsh-subagent-codex-pro/lib/types/jobs.d.ts +34 -0
  93. package/node_modules/dsh-subagent-codex-pro/lib/types/jobs.d.ts.map +1 -0
  94. package/node_modules/dsh-subagent-codex-pro/lib/types/jsonrpc.d.ts +113 -0
  95. package/node_modules/dsh-subagent-codex-pro/lib/types/jsonrpc.d.ts.map +1 -0
  96. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-cli.d.ts +3 -0
  97. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-cli.d.ts.map +1 -0
  98. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-local.d.ts +4 -0
  99. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-local.d.ts.map +1 -0
  100. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-recovery.d.ts +53 -0
  101. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-recovery.d.ts.map +1 -0
  102. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-supervision.d.ts +8 -0
  103. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-supervision.d.ts.map +1 -0
  104. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-supervisor.d.ts +2 -0
  105. package/node_modules/dsh-subagent-codex-pro/lib/types/machine-supervisor.d.ts.map +1 -0
  106. package/node_modules/dsh-subagent-codex-pro/lib/types/machine.d.ts +70 -0
  107. package/node_modules/dsh-subagent-codex-pro/lib/types/machine.d.ts.map +1 -0
  108. package/node_modules/dsh-subagent-codex-pro/lib/types/process-guardian.d.ts +22 -0
  109. package/node_modules/dsh-subagent-codex-pro/lib/types/process-guardian.d.ts.map +1 -0
  110. package/node_modules/dsh-subagent-codex-pro/lib/types/run.d.ts +386 -0
  111. package/node_modules/dsh-subagent-codex-pro/lib/types/run.d.ts.map +1 -0
  112. package/node_modules/dsh-subagent-codex-pro/lib/types/structured.d.ts +35 -0
  113. package/node_modules/dsh-subagent-codex-pro/lib/types/structured.d.ts.map +1 -0
  114. package/node_modules/dsh-subagent-codex-pro/lib/types/tool.d.ts +107 -0
  115. package/node_modules/dsh-subagent-codex-pro/lib/types/tool.d.ts.map +1 -0
  116. package/node_modules/dsh-subagent-codex-pro/lib/types/usage.d.ts +131 -0
  117. package/node_modules/dsh-subagent-codex-pro/lib/types/usage.d.ts.map +1 -0
  118. package/node_modules/dsh-subagent-codex-pro/lib/types/wire.d.ts +321 -0
  119. package/node_modules/dsh-subagent-codex-pro/lib/types/wire.d.ts.map +1 -0
  120. package/node_modules/dsh-subagent-codex-pro/lib/usage.js +356 -0
  121. package/node_modules/dsh-subagent-codex-pro/lib/usage.js.map +1 -0
  122. package/node_modules/dsh-subagent-codex-pro/lib/wire.js +986 -0
  123. package/node_modules/dsh-subagent-codex-pro/lib/wire.js.map +1 -0
  124. package/node_modules/dsh-subagent-codex-pro/package.json +76 -0
  125. package/npm/install.js +59 -6
  126. package/package.json +74 -12
  127. package/plugins/dsh/LICENSE +21 -0
  128. package/plugins/dsh/PROTOCOL.md +607 -0
  129. package/plugins/dsh/README.en.md +4 -0
  130. package/plugins/dsh/README.md +342 -0
  131. package/plugins/dsh/README.zh-CN.md +279 -0
  132. package/plugins/dsh/THIRD_PARTY_NOTICES.md +42 -0
  133. package/plugins/dsh/vendor/README.md +17 -0
  134. package/plugins/dsh/vendor/codex-pro.json +16 -0
@@ -0,0 +1,386 @@
1
+ /**
2
+ * One-shot Codex child lifecycle over the real app-server.
3
+ *
4
+ * The run has one deadline from before startup through the terminal turn. Every
5
+ * startup RPC (initialize, thread/start, thread/resume, thread/name/set) and the
6
+ * turn use the same derived abort signal, so a server that stops answering
7
+ * cannot keep a delegation alive past its budget. Cleanup is a separate, finite
8
+ * grace: the deadline ends work, the grace ends the process range.
9
+ *
10
+ * The child is spawned as the leader of its own POSIX process group. Termination
11
+ * targets the group and then proves it is gone; a descendant that ignores
12
+ * SIGTERM or outlives its parent is reported instead of being silently assumed
13
+ * dead.
14
+ *
15
+ * @module dsh-subagent-codex-pro/run
16
+ */
17
+ import { type JsonRpcMessage } from './jsonrpc.ts';
18
+ import { type AppliedConfiguration, type CodexPermissionMode, type CodexRateLimitsReport, type CodexStopReason, type TurnConfiguration } from './wire.ts';
19
+ import type { CodexImage, CodexThreadMode } from './wire.ts';
20
+ import type { CodexUsageReport } from './usage.ts';
21
+ /** The task text blocks a run accepts. */
22
+ export type PromptBlocks = readonly {
23
+ readonly type: string;
24
+ readonly text?: string;
25
+ }[];
26
+ /** What happened to the process range at cleanup. */
27
+ export interface CleanupReport {
28
+ /** Whether the whole owned process group is confirmed gone. */
29
+ readonly confirmed: boolean;
30
+ /** Why confirmation was impossible, when it was. */
31
+ readonly detail?: string;
32
+ }
33
+ /** Physical facts about one attempt, separate from the model's terminal turn. */
34
+ export interface CodexRunExecution {
35
+ readonly runId: string;
36
+ readonly dispatch: 'not-dispatched' | 'possible' | 'accepted';
37
+ readonly startedAt: string;
38
+ readonly finishedAt: string;
39
+ readonly durationMs: number;
40
+ readonly threadId: string | null;
41
+ readonly turnId: string | null;
42
+ readonly pid: number | null;
43
+ readonly supervisorPid: number | null;
44
+ readonly exitCode: number | null;
45
+ readonly signal: NodeJS.Signals | null;
46
+ readonly supervisorExitCode: number | null;
47
+ readonly supervisorSignal: NodeJS.Signals | null;
48
+ readonly terminationRequested: boolean;
49
+ readonly timedOut: boolean;
50
+ readonly cancelled: boolean;
51
+ readonly truncated: boolean;
52
+ readonly spawnError: string | null;
53
+ readonly failure: FailureFacts | null;
54
+ readonly ownership: 'supervised-group' | 'owned-process';
55
+ }
56
+ /** Everything one run needs that does not change between attempts. */
57
+ export interface CodexRunSpec {
58
+ /** Internal machine correlation selected before the supervised run starts. */
59
+ readonly runId?: string;
60
+ /** The delegating session's working directory. */
61
+ readonly cwd: string;
62
+ /** The Codex executable. */
63
+ readonly command: string;
64
+ /** Unattended permission policy. */
65
+ readonly permissionMode: CodexPermissionMode;
66
+ /** Model requested for this run, when one was chosen. */
67
+ readonly model?: string | undefined;
68
+ /**
69
+ * Per-turn thinking level.
70
+ *
71
+ * Codex carries a thinking level on `turn/start`, not on `thread/start`; the
72
+ * latter is not part of the 0.165/0.166 start parameters. `effort` wins when
73
+ * both are supplied.
74
+ */
75
+ readonly effort?: string | undefined;
76
+ /** Backwards-compatible alias for `effort`; never sent as a thread default. */
77
+ readonly reasoningEffort?: string | undefined;
78
+ /** How long the thread lives. Defaults to `ephemeral`. */
79
+ readonly threadMode?: CodexThreadMode | undefined;
80
+ /**
81
+ * Continue this thread instead of creating one.
82
+ *
83
+ * A thread is resumable only once it has carried a turn, so the caller owns
84
+ * remembering an id it was given earlier.
85
+ */
86
+ readonly resumeThreadId?: string | undefined;
87
+ /** What the app-server records as the thread's originator. */
88
+ readonly originator?: string | undefined;
89
+ /**
90
+ * Deadline for the whole delegation in milliseconds.
91
+ *
92
+ * `0` disables it. Defaults to {@link DEFAULT_RUN_TIMEOUT_MS}.
93
+ */
94
+ readonly runTimeoutMs?: number | undefined;
95
+ /**
96
+ * Absolute deadline shared by an auto-resume retry.
97
+ *
98
+ * Internal: the caller computes this once and passes it to both attempts, so
99
+ * creating a new thread after a failed resume cannot borrow a fresh timeout.
100
+ */
101
+ readonly deadlineAt?: number | undefined;
102
+ /**
103
+ * Absolute paths of images to put in front of Codex with the task.
104
+ *
105
+ * The app-server takes these as `localImage` blocks, so the picture reaches the
106
+ * model as a picture and no bytes travel through the protocol.
107
+ */
108
+ readonly images?: readonly string[] | undefined;
109
+ /**
110
+ * A JSON Schema for the final answer.
111
+ *
112
+ * The app-server enforces it, so the answer arrives as JSON that conforms
113
+ * instead of prose a caller has to parse and hope about. Sent on the turn.
114
+ */
115
+ readonly outputSchema?: Record<string, unknown> | undefined;
116
+ /**
117
+ * A name for a persistent thread, shown in the Codex application's thread list.
118
+ *
119
+ * Ignored for `ephemeral`: a thread that leaves nothing behind has no list to
120
+ * appear in.
121
+ */
122
+ readonly threadName?: string | undefined;
123
+ /** Extra environment entries. */
124
+ readonly env?: Readonly<Record<string, string>> | undefined;
125
+ /** Grace between termination tiers. */
126
+ readonly disposeGraceMs?: number | undefined;
127
+ /** Maximum stdout/stderr bytes before a non-successful, truncated result. */
128
+ readonly maxOutputBytes?: number | undefined;
129
+ /** Narrates notable child activity, for a caller that reports progress. */
130
+ readonly onProgress?: ((text: string) => void) | undefined;
131
+ /** Awaitable structured persistence barriers, independent from progress text. */
132
+ readonly onLifecycle?: ((event: CodexRunLifecycle) => Promise<void> | void) | undefined;
133
+ }
134
+ export interface CodexRunLifecycle {
135
+ readonly event: 'thread-ready' | 'dispatch-intent' | 'dispatch-possible' | 'turn-accepted';
136
+ readonly runId: string;
137
+ readonly threadId: string | null;
138
+ readonly turnId: string | null;
139
+ readonly configuration: AppliedConfiguration | null;
140
+ }
141
+ /** What one finished run reports. */
142
+ export interface CodexRunOutcome {
143
+ readonly output: readonly {
144
+ readonly type: 'text';
145
+ readonly text: string;
146
+ }[];
147
+ readonly stopReason: CodexStopReason;
148
+ readonly diagnostic?: string;
149
+ /**
150
+ * Bounded, package-generated approval/sandbox note, safe for Host diagnostics.
151
+ * Raw server messages and task text are never copied here.
152
+ */
153
+ readonly approvalDiagnostic?: string;
154
+ /**
155
+ * The thread this run used.
156
+ *
157
+ * Reported for every outcome, including a failed one: a persistent thread that
158
+ * half-ran is still a thread the user may want to open or clean up, and it is
159
+ * the only handle `resumeThreadId` accepts.
160
+ */
161
+ readonly threadId?: string | undefined;
162
+ /**
163
+ * Images the run produced.
164
+ *
165
+ * Reported even on a failed run: a screenshot taken before the failure is
166
+ * still a screenshot the user asked for.
167
+ */
168
+ readonly images?: readonly CodexImage[] | undefined;
169
+ /** Token usage attributable to this run; `unknown` rather than zero when absent. */
170
+ readonly usage: CodexUsageReport;
171
+ /** Account rate limits, deliberately separate from token usage. */
172
+ readonly rateLimits: CodexRateLimitsReport;
173
+ /** Requested vs effective model/cwd/permission facts, when startup got that far. */
174
+ readonly configuration?: AppliedConfiguration | undefined;
175
+ /** Whether the process range is confirmed gone. */
176
+ readonly cleanup: CleanupReport;
177
+ readonly execution: CodexRunExecution;
178
+ /** A turn request is evidence of acceptance, not a server effort echo. */
179
+ readonly turnConfiguration?: TurnConfiguration | undefined;
180
+ /** Parsed structured result, only when a schema was supplied and verification passed. */
181
+ readonly structured?: unknown;
182
+ /** Why structured verification failed, when it did. */
183
+ readonly schemaError?: string;
184
+ }
185
+ /** The published run. */
186
+ export interface StartedCodexRun {
187
+ /** A durable id for the harness's catalog. */
188
+ readonly id: string;
189
+ /** Never rejects: a failure arrives as a stop reason plus a diagnostic. */
190
+ readonly result: Promise<CodexRunOutcome>;
191
+ /** Ask the child to stop; local settlement stays authoritative. */
192
+ requestCancel(): void;
193
+ /** Release the process range. Idempotent, and awaited by the caller. */
194
+ teardown(): Promise<CleanupReport>;
195
+ }
196
+ /**
197
+ * How long one delegation may take before it is cancelled.
198
+ *
199
+ * A delegation that hangs is invisible: the job stays `running`, nothing is
200
+ * logged, and the session waits. The deadline turns that into a failure with a
201
+ * reason. Ten minutes is generous against a package whose own README says a
202
+ * delegation takes "a minute or more", and `0` disables it.
203
+ */
204
+ export declare const DEFAULT_RUN_TIMEOUT_MS = 600000;
205
+ /** The failure taxonomy carried out of a run. */
206
+ export interface FailureFacts {
207
+ readonly stage: string;
208
+ readonly category: string;
209
+ readonly httpStatus?: number;
210
+ }
211
+ /** A run failure, kept for its structured facts and any cleanup it observed. */
212
+ export declare class CodexRunFailure extends Error {
213
+ readonly facts: FailureFacts;
214
+ readonly cleanup: CleanupReport | undefined;
215
+ readonly execution: CodexRunExecution | undefined;
216
+ readonly configuration: AppliedConfiguration | undefined;
217
+ readonly usage: CodexUsageReport | undefined;
218
+ readonly rateLimits: CodexRateLimitsReport | undefined;
219
+ readonly turnConfiguration: TurnConfiguration | undefined;
220
+ constructor(facts: FailureFacts, cause?: unknown, cleanup?: CleanupReport, observations?: {
221
+ execution?: CodexRunExecution;
222
+ configuration?: AppliedConfiguration | undefined;
223
+ usage?: CodexUsageReport;
224
+ rateLimits?: CodexRateLimitsReport;
225
+ turnConfiguration?: TurnConfiguration | undefined;
226
+ });
227
+ }
228
+ /** The diagnostic for a delegation the deadline stopped. */
229
+ export declare function describeTimeout(timeoutMs: number): string;
230
+ /**
231
+ * Validate and preserve the one-shot task before crossing the process boundary.
232
+ *
233
+ * @param prompt - the delegation's content blocks.
234
+ * @returns the exact non-empty text block sequence.
235
+ */
236
+ export declare function textTask(prompt: PromptBlocks): string[];
237
+ /** Build the argv, for diagnostics and tests. */
238
+ export declare function codexAppServerArgv(command: string): string[];
239
+ /**
240
+ * Start the app-server child and publish its one-shot run.
241
+ *
242
+ * Resolves only after initialization and thread creation/resume, so a failure
243
+ * before that point rejects with no run published. After publication the result
244
+ * never rejects; even a failed run carries its observed usage, images, thread,
245
+ * configuration, and cleanup report.
246
+ *
247
+ * @param prompt - the delegation's content blocks.
248
+ * @param spec - working directory, executable, permission mode, and choices.
249
+ * @param signal - caller cancellation.
250
+ * @returns the published run.
251
+ */
252
+ export declare function startCodexRun(prompt: PromptBlocks, spec: CodexRunSpec, signal: AbortSignal): Promise<StartedCodexRun>;
253
+ /** The message shapes the wire exchanges, re-exported for diagnostics. */
254
+ export type { JsonRpcMessage };
255
+ /** Which thread a call should continue, if any. */
256
+ export interface ThreadChoice {
257
+ /** The thread to continue, or `undefined` to start a fresh one. */
258
+ readonly reuse: string | undefined;
259
+ /**
260
+ * The remembered thread this call wanted but found busy.
261
+ *
262
+ * Reported rather than dropped: the call still runs, in its own thread, and a
263
+ * log line is the only way to know the session's thread was skipped.
264
+ */
265
+ readonly skippedBusy: string | undefined;
266
+ }
267
+ /**
268
+ * Decide which thread one call continues.
269
+ *
270
+ * `session` mode has one thread per Agent session, but a thread carries one turn
271
+ * at a time: two delegations sent together would otherwise both reach for it and
272
+ * the second would fail. A remembered thread that another delegation is already
273
+ * using is therefore skipped, and this call gets a thread of its own — which is
274
+ * what `persistent` does anyway, so parallel work degrades to the mode that
275
+ * supports it instead of failing and retrying.
276
+ *
277
+ * An id the caller passed explicitly is never skipped: continuing *that* thread
278
+ * was the request, and silently running somewhere else would answer a different
279
+ * question.
280
+ *
281
+ * @param input - the call's explicit id, the configured mode, the session's
282
+ * remembered thread, and the threads currently in flight.
283
+ * @returns the thread to continue and the remembered one that was busy.
284
+ */
285
+ export declare function chooseThread(input: {
286
+ readonly explicit: string | undefined;
287
+ readonly configured: 'ephemeral' | 'persistent' | 'session';
288
+ readonly remembered: string | undefined;
289
+ readonly inFlight: ReadonlySet<string>;
290
+ }): ThreadChoice;
291
+ /**
292
+ * A delegation that did not complete.
293
+ *
294
+ * Carries the thread, images, and (when publication reached the run) the whole
295
+ * outcome, so a caller can report observed usage even though the run failed.
296
+ */
297
+ export declare class CodexDelegationFailure extends Error {
298
+ /** The thread the failed run used, when the app-server had got that far. */
299
+ readonly threadId: string | undefined;
300
+ /** Images the failed run produced before it failed. */
301
+ readonly images: readonly CodexImage[];
302
+ /** Everything observed about the failed run, when one was published. */
303
+ readonly outcome: CodexRunOutcome | undefined;
304
+ constructor(message: string, threadId: string | undefined, images?: readonly CodexImage[], outcome?: CodexRunOutcome);
305
+ }
306
+ /** The successful result of `delegateOnce`, with the observability fields intact. */
307
+ export interface DelegatedCodexRun {
308
+ readonly text: string;
309
+ readonly threadId: string | undefined;
310
+ readonly images: readonly CodexImage[];
311
+ readonly usage: CodexUsageReport;
312
+ readonly rateLimits: CodexRateLimitsReport;
313
+ readonly configuration?: AppliedConfiguration;
314
+ readonly cleanup: CleanupReport;
315
+ readonly execution: CodexRunExecution;
316
+ readonly turnConfiguration?: TurnConfiguration;
317
+ readonly structured?: unknown;
318
+ }
319
+ /** Run one delegation and return its settled outcome. */
320
+ export declare function runCodexOnce(options: {
321
+ readonly prompt: string;
322
+ readonly cwd: string;
323
+ readonly command: string;
324
+ readonly permissionMode: CodexPermissionMode;
325
+ readonly model?: string | undefined;
326
+ readonly reasoningEffort?: string | undefined;
327
+ readonly threadMode?: CodexThreadMode | undefined;
328
+ readonly threadId?: string | undefined;
329
+ readonly originator?: string | undefined;
330
+ readonly threadName?: string | undefined;
331
+ readonly runTimeoutMs?: number | undefined;
332
+ /** Absolute deadline shared with an auto-resume retry. */
333
+ readonly deadlineAt?: number | undefined;
334
+ readonly images?: readonly string[] | undefined;
335
+ readonly outputSchema?: Record<string, unknown> | undefined;
336
+ readonly env?: Readonly<Record<string, string>> | undefined;
337
+ readonly disposeGraceMs?: number | undefined;
338
+ readonly maxOutputBytes?: number | undefined;
339
+ readonly signal: AbortSignal;
340
+ readonly onStart?: ((id: string) => void) | undefined;
341
+ readonly onProgress?: ((text: string) => void) | undefined;
342
+ }): Promise<CodexRunOutcome>;
343
+ /**
344
+ * Run one delegation to completion and return its final text.
345
+ *
346
+ * The result keeps the thread, images, usage, configuration and cleanup report
347
+ * available to callers that need to report more than the answer. A run that
348
+ * does not complete rejects with the whole outcome attached.
349
+ *
350
+ * @param options - the task, its working directory, and the choices.
351
+ * @returns the child's final message and its observability fields.
352
+ * @throws `CodexDelegationFailure` when the run does not complete.
353
+ */
354
+ export declare function delegateOnce(options: {
355
+ readonly prompt: string;
356
+ readonly cwd: string;
357
+ readonly command: string;
358
+ readonly permissionMode: CodexPermissionMode;
359
+ readonly model?: string | undefined;
360
+ readonly reasoningEffort?: string | undefined;
361
+ /** How long the thread lives. Defaults to `ephemeral`. */
362
+ readonly threadMode?: CodexThreadMode | undefined;
363
+ /** Continue this thread instead of creating one. */
364
+ readonly threadId?: string | undefined;
365
+ /** What the app-server records as the thread's originator. */
366
+ readonly originator?: string | undefined;
367
+ /** A name for a persistent thread, shown in the Codex application. */
368
+ readonly threadName?: string | undefined;
369
+ /** Deadline for the whole delegation in milliseconds; `0` disables it. */
370
+ readonly runTimeoutMs?: number | undefined;
371
+ /** Absolute deadline shared with an auto-resume retry. */
372
+ readonly deadlineAt?: number | undefined;
373
+ /** Absolute paths of images to show Codex alongside the task. */
374
+ readonly images?: readonly string[] | undefined;
375
+ /** A JSON Schema the final answer must conform to. */
376
+ readonly outputSchema?: Record<string, unknown> | undefined;
377
+ readonly env?: Readonly<Record<string, string>> | undefined;
378
+ readonly disposeGraceMs?: number | undefined;
379
+ readonly maxOutputBytes?: number | undefined;
380
+ readonly signal: AbortSignal;
381
+ /** Called once the run is published, for diagnostics. */
382
+ readonly onStart?: (id: string) => void;
383
+ /** Narrates notable child activity. */
384
+ readonly onProgress?: ((text: string) => void) | undefined;
385
+ }): Promise<DelegatedCodexRun>;
386
+ //# sourceMappingURL=run.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/run.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Structured-output verification.
3
+ *
4
+ * Codex enforces the schema it was given, but a completed turn is not proof that
5
+ * the answer the host received is valid JSON or that it still matches the
6
+ * schema: the app-server can be replaced, a stub can answer, and a later change
7
+ * to the wire can hand the caller prose. Treating an unparseable answer as
8
+ * "structured output absent" would report exactly the success the caller asked
9
+ * to avoid, so this module fails closed and returns the reason.
10
+ *
11
+ * The validator deliberately covers the JSON Schema subset this plugin accepts
12
+ * for `output_schema` (object-rooted schemas using the common assertion
13
+ * keywords). A schema using a keyword outside that subset is reported as an
14
+ * error rather than silently accepted; the plugin never claims a validation it
15
+ * did not perform.
16
+ *
17
+ * @module dsh-subagent-codex-pro/structured
18
+ */
19
+ /** The verification result for one schema-constrained answer. */
20
+ export type StructuredVerification = {
21
+ readonly ok: true;
22
+ readonly value: unknown;
23
+ } | {
24
+ readonly ok: false;
25
+ readonly error: string;
26
+ };
27
+ /**
28
+ * Parse and validate one schema-constrained final answer.
29
+ *
30
+ * @param text - the final answer text, exactly as Codex returned it.
31
+ * @param schema - the object-rooted schema the answer was asked to conform to.
32
+ * @returns the decoded value, or the reason verification failed.
33
+ */
34
+ export declare function verifyStructuredOutput(text: string, schema: unknown): StructuredVerification;
35
+ //# sourceMappingURL=structured.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"structured.d.ts","sourceRoot":"","sources":["../../src/structured.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iEAAiE;AACjE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAmQlD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,sBAAsB,CAkB5F"}
@@ -0,0 +1,107 @@
1
+ /**
2
+ * The model-facing delegation tool.
3
+ *
4
+ * `@deepseek-ai/dsh-tool-subagent` cannot give an external provider the model
5
+ * surface: a row may only carry `modelSelectionSettings: true` when the provider
6
+ * declares `agentOptions`, and enabling it on the Codex row inside a preset
7
+ * makes that row disappear — silently, with no tool and no error. The control
8
+ * row in those experiments (same provider, same row, flag off) did register, so
9
+ * the provider and the row shape are both fine.
10
+ *
11
+ * So this plugin registers the tool itself, the way the LCU plugin registers
12
+ * `js`: on `agent/created`, into that agent's own context. `model` and
13
+ * `reasoning_effort` appear while this plugin's modelSelection setting is
14
+ * enabled; that setting is independent of the Host LLM route picker.
15
+ *
16
+ * @module dsh-subagent-codex-pro/tool
17
+ */
18
+ import type { ToolDefinitionLike } from './dsh-types.ts';
19
+ import type { CodexPermissionMode } from './wire.ts';
20
+ /** One call's choices, already resolved against the configured defaults. */
21
+ export interface CodexCall {
22
+ readonly label: string;
23
+ readonly prompt: string;
24
+ readonly model?: string;
25
+ readonly reasoningEffort?: string;
26
+ /** Per-call permission mode override, when the caller chose one. */
27
+ readonly permissionMode?: CodexPermissionMode;
28
+ /** How long this delegation's thread lives, when the call chose. */
29
+ readonly threadMode?: 'ephemeral' | 'persistent';
30
+ /** Continue this thread instead of creating one. */
31
+ readonly threadId?: string;
32
+ /** Working directory for the delegation, when the call named one. */
33
+ readonly cwd?: string;
34
+ /** Absolute paths of images to show Codex alongside the task. */
35
+ readonly images?: readonly string[];
36
+ /** A JSON Schema the final answer must conform to. */
37
+ readonly outputSchema?: Record<string, unknown>;
38
+ /** Deadline for this call in milliseconds; `0` means no deadline. */
39
+ readonly timeoutMs?: number;
40
+ }
41
+ /** Everything the tool needs that does not change per call. */
42
+ export interface CodexToolOptions {
43
+ /** The delegating Agent's working directory. */
44
+ readonly cwd: string;
45
+ /** Default model when a call does not name one. */
46
+ readonly model?: string;
47
+ /** Default reasoning effort when a call does not name one. */
48
+ readonly reasoningEffort?: string;
49
+ /** Configured permission policy; limits the per-call enum to safe choices. */
50
+ readonly permissionMode?: CodexPermissionMode;
51
+ /**
52
+ * Whether the plugin permits Agent-chosen Codex models.
53
+ *
54
+ * When false the tool exposes no `model` or `reasoning_effort`, exactly as the
55
+ * harness's own delegation tools behave — the user's authorization is the only
56
+ * thing that makes those fields exist.
57
+ */
58
+ readonly modelSelectionEnabled: boolean;
59
+ /** Whether the jobs service is present, which is what makes background runs possible. */
60
+ readonly backgroundEnabled: boolean;
61
+ /** The plugin's configured thread mode, named in the tool description. */
62
+ readonly defaultThreadMode: 'ephemeral' | 'persistent' | 'session';
63
+ /** Whether a call may override the thread mode and resume a thread. */
64
+ readonly threadControlEnabled: boolean;
65
+ /** Run one delegation and return its final text and the thread it used. */
66
+ readonly run: (request: CodexCall & {
67
+ readonly signal: AbortSignal;
68
+ }) => Promise<{
69
+ readonly text: string;
70
+ readonly threadId: string | undefined;
71
+ /**
72
+ * Content blocks to hand the model, when the run produced more than text.
73
+ *
74
+ * A foreground delegation returns these so a screenshot the run took reaches
75
+ * the model as an image. A background job's result is a string by contract,
76
+ * so its images are reported by host path in the text instead.
77
+ */
78
+ readonly blocks?: readonly {
79
+ readonly type: string;
80
+ }[] | undefined;
81
+ }>;
82
+ /**
83
+ * Start one delegation as a background job.
84
+ *
85
+ * @param request - the call's label and resolved choices.
86
+ * @returns the job id the model collects with `job_output`.
87
+ */
88
+ readonly startBackground: (request: CodexCall) => string;
89
+ }
90
+ /**
91
+ * Permission modes a per-call override may select without changing the
92
+ * configured policy upward.
93
+ *
94
+ * The tool description and schema should not advertise a choice that the
95
+ * runtime's narrowing guard will reject. When no policy is supplied (direct
96
+ * tests or older callers), all modes remain visible for compatibility.
97
+ */
98
+ export declare function allowedPermissionModes(configured: CodexPermissionMode | undefined): readonly CodexPermissionMode[];
99
+ /**
100
+ * Build the delegation tool definition.
101
+ *
102
+ * @param options - the delegating Agent's fixed choices, its runner, and its
103
+ * background starter.
104
+ * @returns a definition ready for `agent.ctx.tools.register`.
105
+ */
106
+ export declare function createCodexTool(options: CodexToolOptions): ToolDefinitionLike;
107
+ //# sourceMappingURL=tool.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAA;IAC7C,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,GAAG,YAAY,CAAA;IAChD,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/C,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAA;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAA;IACvC,yFAAyF;IACzF,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,CAAA;IAClE,uEAAuE;IACvE,QAAQ,CAAC,oBAAoB,EAAE,OAAO,CAAA;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,SAAS,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC;QAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;QACrC;;;;;;WAMG;QACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;SAAE,EAAE,GAAG,SAAS,CAAA;KACnE,CAAC,CAAA;IACF;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,MAAM,CAAA;CACzD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAC1C,SAAS,mBAAmB,EAAE,CAOhC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAiP7E"}