The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 22, 18:15 UTC
feat(server): request_secret can save a CLI token to a private file (#24809)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Theo Browne committed
Oct 25, 2026 at 02:28 UTC
e0b194021b151cd28e718f4cecd10095134dee45
13 files changed
+264
-13
apps/mobile/src/features/threads/SecretRequestCard.tsx
+2
-2
@@ -1,9 +1,9 @@
1
import {
2
SECRET_REQUEST_DEFAULT_PLACEHOLDER,
3
- SECRET_REQUEST_PRIVACY_NOTE,
3
secretRequestAnswerInput,
4
secretRequestDisplay,
5
secretRequestFailureMessage,
6
+ secretRequestPrivacyNote,
7
type SecretRequestItem,
8
} from "@t3tools/client-runtime/secret-request";
9
import {
@@ -144,7 +144,7 @@ function PendingSecretRequestForm(props: {
144
type="monochrome"
145
/>
146
<Text className="flex-1 font-sans text-xs text-foreground-muted">
147
- {SECRET_REQUEST_PRIVACY_NOTE}
147
+ {secretRequestPrivacyNote(item)}
148
</Text>
149
</View>
150
<Button
apps/server/src/mcp/OrchestratorMcpService.ts
+7
@@ -1969,6 +1969,7 @@ const make = Effect.gen(function* () {
1969
label: input.label,
1970
reason: input.reason,
1971
...(input.placeholder === undefined ? {} : { placeholder: input.placeholder }),
1972
+ ...(input.delivery === "file" ? { delivery: "file" as const } : {}),
1973
secretStatus,
1974
})
1975
.pipe(
@@ -2047,6 +2048,12 @@ const make = Effect.gen(function* () {
2048
yield* Effect.annotateCurrentSpan({ "secret_request.status": status });
2049
yield* Metrics.increment(Metrics.secretRequestsTotal, { status });
2050
if (status !== "saved") return { status };
2051
+ if (input.delivery === "file") {
2052
+ const file = yield* secretRequests
2053
+ .saveToFile({ threadId, turnItemId })
2054
+ .pipe(Effect.mapError((error) => failure("orchestration_error", error.message)));
2055
+ return { status, file };
2056
+ }
2057
const secretRef = yield* secretRequests.savedRef({ threadId: threadId, turnItemId });
2058
if (Option.isNone(secretRef)) {
2059
return yield* failure(
apps/server/src/mcp/toolkits/orchestrator/tools.ts
+1
-1
@@ -189,7 +189,7 @@ const DeleteScheduledTaskTool = Tool.make("delete_scheduled_task", {
189
190
const RequestSecretTool = Tool.make("request_secret", {
191
description:
192
- "Ask the user for a secret (a token, API key, signing secret, password) through a private card in this thread, and wait for them to answer. The value is kept by the app and NEVER returned to you or shown in the transcript. When saved, the result carries a secretRef: pass it to a tool that accepts one (e.g. schedule_task's signature.secretRef). It works once. Never ask for secrets in chat, and never invent one.",
192
+ "Ask the user for a secret (a token, API key, signing secret, password) through a private card in this thread, and wait for them to answer. The value is NEVER returned to you or shown in the transcript. By default the result carries a one-use secretRef for a tool that accepts one (e.g. schedule_task's signature.secretRef). For a shell CLI token, set delivery to file. Never ask for secrets in chat, and never invent one.",
193
parameters: OrchestratorMcpRequestSecretInput,
194
success: OrchestratorMcpRequestSecretResult,
195
failure: OrchestratorMcpFailure,
apps/server/src/orchestration-v2/Orchestrator.ts
+1
@@ -7749,6 +7749,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
7749
label: command.label,
7750
reason: command.reason,
7751
...(command.placeholder === undefined ? {} : { placeholder: command.placeholder }),
7752
+ ...(command.delivery === undefined ? {} : { delivery: command.delivery }),
7753
secretStatus: command.secretStatus,
7754
};
7755
yield* emit(
apps/server/src/secrets/SecretRequests.test.ts
+119
@@ -1,18 +1,23 @@
1
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
2
import * as NodeServices from "@effect/platform-node/NodeServices";
3
import { assert, it } from "@effect/vitest";
4
+import * as HostProcess from "@t3tools/shared/HostProcess";
5
import {
6
ProjectId,
7
type OrchestrationV2ServerCommand,
8
+ SecretRef,
9
ThreadId,
10
TurnItemId,
11
} from "@t3tools/contracts";
12
import * as Effect from "effect/Effect";
13
+import * as FileSystem from "effect/FileSystem";
14
import * as Layer from "effect/Layer";
15
import * as Metric from "effect/Metric";
16
import * as Tracer from "effect/Tracer";
17
import * as Option from "effect/Option";
18
+import * as Path from "effect/Path";
19
import * as PlatformError from "effect/PlatformError";
20
+import * as TestClock from "effect/testing/TestClock";
21
22
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
23
import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
@@ -30,6 +35,8 @@ const withService = <A, E>(
35
}) => Effect.Effect<A, E>,
36
options: {
37
readonly threadId?: ThreadId;
38
+ readonly delivery?: "file";
39
+ readonly directory?: string;
40
readonly runStatus?: string;
41
readonly removeFails?: boolean;
42
readonly closedFirst?: boolean;
@@ -48,6 +55,7 @@ const withService = <A, E>(
55
Layer.succeed(
56
ServerSecretStore.ServerSecretStore,
57
ServerSecretStore.ServerSecretStore.of({
58
+ ...(options.directory === undefined ? {} : { directory: options.directory }),
59
get: (name) => Effect.yieldNow.pipe(Effect.as(Option.fromNullishOr(stored.get(name)))),
60
set: (name, value) => Effect.sync(() => void stored.set(name, value)),
61
create: (name, value) =>
@@ -98,6 +106,7 @@ const withService = <A, E>(
106
type: "secret_request",
107
label: "GitHub token",
108
reason: "Used as GH_TOKEN.",
109
+ ...(options.delivery === undefined ? {} : { delivery: options.delivery }),
110
secretStatus,
111
},
112
],
@@ -338,3 +347,113 @@ it.effect("a used value that cannot be deleted is not handed out", () =>
347
{ removeFails: true },
348
),
349
);
350
+
351
+const SECRET_FILE_TTL_MS = 24 * 60 * 60 * 1000;
352
+
353
+it.effect("a file request moves its value to an owner-only file, once", () =>
354
+ Effect.gen(function* () {
355
+ const fs = yield* FileSystem.FileSystem;
356
+ const path = yield* Path.Path;
357
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "secret-files-test-" });
358
+ const file = yield* withService(
359
+ ({ service, stored, dispatched }) =>
360
+ Effect.gen(function* () {
361
+ yield* service.answer({
362
+ threadId,
363
+ turnItemId,
364
+ answer: { type: "save", secret: "cf_token'$(id)" },
365
+ });
366
+ assert.include(dispatched[0] as object, { secretStatus: "saved", delivery: "file" });
367
+ const file = yield* service.saveToFile({ threadId, turnItemId });
368
+ assert.equal(yield* fs.readFileString(file), "cf_token'$(id)");
369
+ assert.deepEqual(valuesOf(stored), []);
370
+ if ((yield* HostProcess.Platform) !== "win32") {
371
+ assert.equal((yield* fs.stat(file)).mode & 0o777, 0o600);
372
+ assert.equal((yield* fs.stat(path.dirname(file))).mode & 0o777, 0o700);
373
+ }
374
+ // A retried request_secret gets the same file; the value is never a ref again.
375
+ assert.equal(yield* service.saveToFile({ threadId, turnItemId }), file);
376
+ const ref = SecretRef.make(`secret-ref:${path.basename(file)}`);
377
+ const reused = yield* service.consume({ ref, projectId }).pipe(Effect.flip);
378
+ assert.equal(reused.reason, "ref_unavailable");
379
+ return file;
380
+ }),
381
+ { delivery: "file", directory },
382
+ );
383
+
384
+ const { mtime } = yield* fs.stat(file);
385
+ yield* TestClock.setTime(Option.getOrThrow(mtime).getTime() + SECRET_FILE_TTL_MS);
386
+ yield* withService(() => Effect.void, { directory });
387
+ assert.isTrue(yield* fs.exists(file));
388
+ yield* TestClock.setTime(Option.getOrThrow(mtime).getTime() + SECRET_FILE_TTL_MS + 1);
389
+ yield* withService(() => Effect.void, { directory });
390
+ assert.isFalse(yield* fs.exists(file));
391
+ }).pipe(Effect.provide(NodeServices.layer)),
392
+);
393
+
394
+it.effect("a failed file write keeps the value, so the request can retry", () =>
395
+ Effect.gen(function* () {
396
+ const fs = yield* FileSystem.FileSystem;
397
+ const path = yield* Path.Path;
398
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "secret-files-test-" });
399
+ yield* withService(
400
+ ({ service }) =>
401
+ Effect.gen(function* () {
402
+ yield* service.answer({
403
+ threadId,
404
+ turnItemId,
405
+ answer: { type: "save", secret: "cf_token" },
406
+ });
407
+ const ref = Option.getOrThrow(yield* service.savedRef({ threadId, turnItemId }));
408
+ const name = ref.slice("secret-ref:".length);
409
+ // A non-empty directory where the partial file goes makes the write fail.
410
+ const partial = path.join(directory, "files", `${name}.partial`);
411
+ yield* fs.makeDirectory(path.join(partial, "block"), { recursive: true });
412
+ const failed = yield* service.saveToFile({ threadId, turnItemId }).pipe(Effect.flip);
413
+ assert.equal(failed.reason, "store_failed");
414
+ yield* fs.remove(partial, { recursive: true });
415
+ const file = yield* service.saveToFile({ threadId, turnItemId });
416
+ assert.equal(yield* fs.readFileString(file), "cf_token");
417
+ }),
418
+ { delivery: "file", directory },
419
+ );
420
+ }).pipe(Effect.provide(NodeServices.layer)),
421
+);
422
+
423
+it.effect("a file is not delivered while its stored copy cannot be removed", () =>
424
+ Effect.gen(function* () {
425
+ const fs = yield* FileSystem.FileSystem;
426
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "secret-files-test-" });
427
+ yield* withService(
428
+ ({ service }) =>
429
+ Effect.gen(function* () {
430
+ yield* service.answer({
431
+ threadId,
432
+ turnItemId,
433
+ answer: { type: "save", secret: "cf_token" },
434
+ });
435
+ const first = yield* service.saveToFile({ threadId, turnItemId }).pipe(Effect.flip);
436
+ assert.equal(first.reason, "consume_failed");
437
+ // A retry finds the file but still will not hand it out until the removal works.
438
+ const retried = yield* service.saveToFile({ threadId, turnItemId }).pipe(Effect.flip);
439
+ assert.equal(retried.reason, "consume_failed");
440
+ }),
441
+ { delivery: "file", directory, removeFails: true },
442
+ );
443
+ }).pipe(Effect.provide(NodeServices.layer)),
444
+);
445
+
446
+it.effect("a secret the card promised to keep from the agent is never written to a file", () =>
447
+ withService(({ service, stored }) =>
448
+ Effect.gen(function* () {
449
+ yield* service.answer({
450
+ threadId,
451
+ turnItemId,
452
+ answer: { type: "save", secret: "ghp_secret" },
453
+ });
454
+ const refused = yield* service.saveToFile({ threadId, turnItemId }).pipe(Effect.flip);
455
+ assert.equal(refused.reason, "not_a_file_request");
456
+ assert.isTrue(valuesOf(stored).some((value) => value.includes("ghp_secret")));
457
+ }),
458
+ ),
459
+);
apps/server/src/secrets/SecretRequests.ts
+96
-5
@@ -1,5 +1,6 @@
1
// Answers stay in the secret store behind one-use refs; orchestration records only request status.
2
// Consuming tools keep values out of transcripts, projections, clients and model context.
3
+// A `file` request instead moves its value to an owner-only file for the agent's own shell.
4
import {
5
CommandId,
6
SecretRef,
@@ -17,6 +18,7 @@ import * as Effect from "effect/Effect";
18
import * as FileSystem from "effect/FileSystem";
19
import * as Layer from "effect/Layer";
20
import * as Option from "effect/Option";
21
+import * as Path from "effect/Path";
22
import * as Schedule from "effect/Schedule";
23
import * as Schema from "effect/Schema";
24
import * as Semaphore from "effect/Semaphore";
@@ -30,6 +32,7 @@ const storeName = (ref: SecretRef) => `secret-request-${ref.slice(SECRET_REF_PRE
32
const REF_PATTERN = /^secret-ref:[0-9a-f]{32}$/;
33
const SECRET_REF_TTL_MS = 24 * 60 * 60 * 1000;
34
const STORE_NAME_PATTERN = /^(secret-request-[0-9a-f]{32})\.bin$/;
35
+const FILE_NAME_PATTERN = /^[0-9a-f]{32}(\.partial)?$/;
36
37
const refFor = (salt: string, threadId: ThreadId, turnItemId: string) =>
38
SecretRef.make(
@@ -57,13 +60,21 @@ export class SecretRequests extends Context.Service<
60
readonly ref: SecretRef;
61
readonly projectId: ProjectId;
62
}) => Effect.Effect<string, SecretRequestError>;
63
+ /** Moves a saved `file` request's value to an owner-only file and returns its path. */
64
+ readonly saveToFile: (input: {
65
+ readonly threadId: ThreadId;
66
+ readonly turnItemId: string;
67
+ }) => Effect.Effect<string, SecretRequestError>;
68
}
69
>()("t3/secrets/SecretRequests") {}
70
71
const make = Effect.gen(function* () {
72
const store = yield* ServerSecretStore.ServerSecretStore;
73
const fileSystem = yield* FileSystem.FileSystem;
74
+ const path = yield* Path.Path;
75
const threadManagement = yield* ThreadManagementService.ThreadManagementService;
76
+ // Beside the store's own files so the same owner-only directory and cleanup rules apply.
77
+ const filesDir = store.directory === undefined ? undefined : path.join(store.directory, "files");
78
79
const salt = Buffer.from(
80
yield* store.getOrCreateRandom("secret-request-salt", 32).pipe(Effect.orDie),
@@ -124,6 +135,7 @@ const make = Effect.gen(function* () {
135
label: item.label,
136
reason: item.reason,
137
...(item.placeholder === undefined ? {} : { placeholder: item.placeholder }),
138
+ ...(item.delivery === undefined ? {} : { delivery: item.delivery }),
139
secretStatus,
140
})
141
.pipe(
@@ -183,7 +195,8 @@ const make = Effect.gen(function* () {
195
Effect.withSpan("SecretRequests.consume"),
196
);
197
186
- const consumeRef = Effect.fn("SecretRequests.consumeRef")(function* (input: {
198
+ /** A live ref's value, left in the store. */
199
+ const readRef = Effect.fn("SecretRequests.readRef")(function* (input: {
200
readonly ref: SecretRef;
201
readonly projectId: ProjectId;
202
}) {
@@ -202,12 +215,72 @@ const make = Effect.gen(function* () {
215
yield* removeLogged(storeName(input.ref));
216
return yield* new SecretRequestError({ reason: "ref_expired" });
217
}
218
+ return decoded.value.value;
219
+ });
220
+
221
+ const consumeRef = Effect.fn("SecretRequests.consumeRef")(function* (input: {
222
+ readonly ref: SecretRef;
223
+ readonly projectId: ProjectId;
224
+ }) {
225
+ const value = yield* readRef(input);
226
// One use: the value moves into whatever consumed it. If it cannot be
227
// deleted, it is not handed out, so a ref is never used twice.
228
if (!(yield* removeLogged(storeName(input.ref)))) {
229
return yield* new SecretRequestError({ reason: "consume_failed" });
230
}
210
- return decoded.value.value;
231
+ return value;
232
+ });
233
+
234
+ const saveToFile: SecretRequests["Service"]["saveToFile"] = Effect.fn(
235
+ "SecretRequests.saveToFile",
236
+ )(function* (input) {
237
+ const records = yield* threadManagement
238
+ .getThreadRecords(input.threadId, ["turnItems"], {
239
+ turnItemTypes: ["secret_request"],
240
+ messageRoles: [],
241
+ })
242
+ .pipe(Effect.mapError((cause) => new SecretRequestError({ reason: "load_failed", cause })));
243
+ const item = records.turnItems.find((candidate) => candidate.id === input.turnItemId);
244
+ // Only a card that told the user the agent's commands can read the value may write it out.
245
+ if (
246
+ item?.type !== "secret_request" ||
247
+ item.secretStatus !== "saved" ||
248
+ item.delivery !== "file"
249
+ ) {
250
+ return yield* new SecretRequestError({ reason: "not_a_file_request" });
251
+ }
252
+ if (filesDir === undefined) return yield* new SecretRequestError({ reason: "store_failed" });
253
+ const ref = refFor(salt, input.threadId, item.id);
254
+ const file = path.join(filesDir, ref.slice(SECRET_REF_PREFIX.length));
255
+ return yield* Effect.gen(function* () {
256
+ // One use: the file counts as delivered only once the stored copy is gone. A retry with the
257
+ // same clientRequestId gets the file the first call wrote and finishes that removal.
258
+ const removeStored = removeLogged(storeName(ref)).pipe(
259
+ Effect.flatMap((removed) =>
260
+ removed ? Effect.succeed(file) : new SecretRequestError({ reason: "consume_failed" }),
261
+ ),
262
+ );
263
+ if (yield* fileSystem.exists(file).pipe(Effect.orElseSucceed(() => false))) {
264
+ return yield* removeStored;
265
+ }
266
+ // The stored value goes only after the file is complete, so a failed write can retry.
267
+ const value = yield* readRef({ ref, projectId: records.thread.projectId });
268
+ const partial = `${file}.partial`;
269
+ yield* fileSystem.makeDirectory(filesDir, { recursive: true, mode: 0o700 }).pipe(
270
+ Effect.andThen(fileSystem.chmod(filesDir, 0o700)),
271
+ Effect.andThen(fileSystem.remove(partial, { force: true })),
272
+ // `wx` never follows or replaces an existing path.
273
+ Effect.andThen(
274
+ fileSystem.writeFile(partial, new TextEncoder().encode(value), {
275
+ flag: "wx",
276
+ mode: 0o600,
277
+ }),
278
+ ),
279
+ Effect.andThen(fileSystem.rename(partial, file)),
280
+ Effect.mapError((cause) => new SecretRequestError({ reason: "store_failed", cause })),
281
+ );
282
+ return yield* removeStored;
283
+ }).pipe(consumeLock.withPermits(1));
284
});
285
286
const sweepExpired = Effect.gen(function* () {
@@ -231,14 +304,32 @@ const make = Effect.gen(function* () {
304
Effect.catchCause((cause) => Effect.logWarning("Could not sweep expired secret refs", cause)),
305
Effect.withSpan("SecretRequests.sweepExpired"),
306
);
234
- yield* sweepExpired;
235
- yield* sweepExpired.pipe(
307
+ const sweepExpiredFiles = Effect.gen(function* () {
308
+ if (filesDir === undefined || !(yield* fileSystem.exists(filesDir))) return;
309
+ const now = yield* Clock.currentTimeMillis;
310
+ let removed = 0;
311
+ for (const name of yield* fileSystem.readDirectory(filesDir)) {
312
+ if (!FILE_NAME_PATTERN.test(name)) continue;
313
+ const file = path.join(filesDir, name);
314
+ const { mtime } = yield* fileSystem.stat(file);
315
+ if (Option.exists(mtime, (time) => now - time.getTime() <= SECRET_REF_TTL_MS)) continue;
316
+ yield* fileSystem.remove(file);
317
+ removed += 1;
318
+ }
319
+ yield* Effect.annotateCurrentSpan({ "secret_request.expired_files_removed": removed });
320
+ }).pipe(
321
+ Effect.catchCause((cause) => Effect.logWarning("Could not sweep expired secret files", cause)),
322
+ Effect.withSpan("SecretRequests.sweepExpiredFiles"),
323
+ );
324
+ const sweep = Effect.andThen(sweepExpired, sweepExpiredFiles);
325
+ yield* sweep;
326
+ yield* sweep.pipe(
327
Effect.delay("1 hour"),
328
Effect.repeat(Schedule.spaced("1 hour")),
329
Effect.forkScoped,
330
);
331
241
- return SecretRequests.of({ answer, savedRef, consume });
332
+ return SecretRequests.of({ answer, savedRef, consume, saveToFile });
333
});
334
335
export const layer = Layer.effect(SecretRequests, make);
apps/web/src/components/chat/SecretRequestCard.tsx
+2
-2
@@ -1,9 +1,9 @@
1
import {
2
SECRET_REQUEST_DEFAULT_PLACEHOLDER,
3
- SECRET_REQUEST_PRIVACY_NOTE,
3
secretRequestAnswerInput,
4
secretRequestDisplay,
5
secretRequestFailureMessage,
6
+ secretRequestPrivacyNote,
7
type SecretRequestItem,
8
} from "@t3tools/client-runtime/secret-request";
9
import {
@@ -150,7 +150,7 @@ function PendingSecretRequestForm(props: {
150
className="flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground"
151
>
152
<ShieldCheckIcon className="size-3.5 shrink-0" aria-hidden />
153
- {SECRET_REQUEST_PRIVACY_NOTE}
153
+ {secretRequestPrivacyNote(item)}
154
</p>
155
<Button
156
type="button"
packages/client-runtime/src/secretRequest.test.ts
+12
-1
@@ -1,7 +1,11 @@
1
import { SecretRequestError } from "@t3tools/contracts";
2
import { describe, expect, it } from "vite-plus/test";
3
4
-import { secretRequestDisplay, secretRequestFailureMessage } from "./secretRequest.ts";
4
+import {
5
+ secretRequestDisplay,
6
+ secretRequestFailureMessage,
7
+ secretRequestPrivacyNote,
8
+} from "./secretRequest.ts";
9
10
describe("secretRequestDisplay", () => {
11
it("never offers the form for a request inherited from another thread", () => {
@@ -15,6 +19,13 @@ describe("secretRequestDisplay", () => {
19
});
20
});
21
22
+describe("secretRequestPrivacyNote", () => {
23
+ it("does not promise to hide a value that the agent's commands can read", () => {
24
+ expect(secretRequestPrivacyNote({})).toBe("Stored securely, never shown to the agent");
25
+ expect(secretRequestPrivacyNote({ delivery: "file" })).not.toContain("never shown");
26
+ });
27
+});
28
+
29
describe("secretRequestFailureMessage", () => {
30
it("passes through server errors but hides anything that could echo the payload", () => {
31
expect(
packages/client-runtime/src/secretRequest.ts
+5
-1
@@ -5,7 +5,11 @@ export type SecretRequestItem = Extract<
5
{ readonly type: "secret_request" }
6
>;
7
8
-export const SECRET_REQUEST_PRIVACY_NOTE = "Stored securely, never shown to the agent";
8
+/** A `file` request lets the agent's commands read the value, so its card must not promise more. */
9
+export const secretRequestPrivacyNote = (item: Pick<SecretRequestItem, "delivery">) =>
10
+ item.delivery === "file"
11
+ ? "Kept out of chat, in a private file this agent's commands can read for 24 hours"
12
+ : "Stored securely, never shown to the agent";
13
export const SECRET_REQUEST_DEFAULT_PLACEHOLDER = "Paste the secret";
14
15
export type SecretRequestDisplay =
packages/contracts/src/orchestrationV2.ts
+5
@@ -1391,11 +1391,15 @@ export const OrchestrationV2SecretRequestStatus = Schema.Literals([
1391
]);
1392
export type OrchestrationV2SecretRequestStatus = typeof OrchestrationV2SecretRequestStatus.Type;
1393
1394
+/** `file`: the value goes to an owner-only file the agent's shell commands can read. */
1395
+export const OrchestrationV2SecretRequestDelivery = Schema.Literal("file");
1396
+
1397
const OrchestrationV2SecretRequestFields = {
1398
type: Schema.Literal("secret_request"),
1399
label: TrimmedNonEmptyString,
1400
reason: Schema.String,
1401
placeholder: Schema.optional(Schema.String),
1402
+ delivery: Schema.optional(OrchestrationV2SecretRequestDelivery),
1403
secretStatus: OrchestrationV2SecretRequestStatus,
1404
} as const;
1405
@@ -3230,6 +3234,7 @@ const OrchestrationV2InternalCommand = Schema.Union([
3234
label: TrimmedNonEmptyString,
3235
reason: Schema.String,
3236
placeholder: Schema.optional(Schema.String),
3237
+ delivery: Schema.optional(OrchestrationV2SecretRequestDelivery),
3238
secretStatus: OrchestrationV2SecretRequestStatus,
3239
}),
3240
]);
packages/contracts/src/orchestratorMcp.ts
+11
@@ -670,6 +670,10 @@ export const OrchestratorMcpRequestSecretInput = Schema.Struct({
670
placeholder: Schema.optional(TrimmedNonEmptyString).annotate({
671
description: "Hint inside the input, e.g. 'Paste your GitHub token'.",
672
}),
673
+ delivery: Schema.optional(Schema.Literals(["secretRef", "file"])).annotate({
674
+ description:
675
+ 'secretRef (default): for a T3 tool that takes one. file: for a shell CLI; the result is a private file path to read inside your command, e.g. CLOUDFLARE_API_TOKEN="$(cat <file>)" wrangler whoami.',
676
+ }),
677
timeoutMs: Schema.optional(
678
Schema.Int.check(Schema.isBetween({ minimum: 1_000, maximum: 60 * 60 * 1_000 })),
679
).annotate({ description: "How long to wait for the user. Default 10 minutes." }),
@@ -688,6 +692,13 @@ export const OrchestratorMcpRequestSecretResult = Schema.Union([
692
"Pass it to a tool that accepts a secretRef; it works once, and you never see the value.",
693
}),
694
}),
695
+ Schema.Struct({
696
+ status: Schema.Literal("saved").annotate({ description: "file holds the value." }),
697
+ file: Schema.String.annotate({
698
+ description:
699
+ "Owner-only file with the value. Read it inside commands and never print it. Deleted after 24 hours.",
700
+ }),
701
+ }),
702
Schema.Struct({
703
status: Schema.Literals(["declined", "cancelled", "timed_out"]).annotate({
704
description:
packages/contracts/src/secretRequest.ts
+2
@@ -26,6 +26,8 @@ const SECRET_REQUEST_FAILURE_MESSAGES = {
26
"That secretRef was already used or does not exist. Ask the user again with request_secret.",
27
ref_expired: "That secretRef expired. Ask the user again with request_secret.",
28
consume_failed: "Could not use that secretRef. Try again.",
29
+ not_a_file_request:
30
+ 'The user did not save this secret for shell use. Ask again with request_secret and delivery: "file".',
31
} as const;
32
33
export const SecretRequestFailureReason = Schema.Literals(
packages/provider-core/src/server/orchestrationInstructions.ts
+1
-1
@@ -10,7 +10,7 @@ The \`t3-code\` MCP server provides app-owned orchestration. Treat these concept
10
- \`t3_thread_launch\` and \`create_threads\` create ordinary top-level T3 conversations. Use them only when the user explicitly asks for separate/new/top-level threads or conversations. Never use them merely because the user said "subagent" or requested parallel delegated work.
11
- For independent T3 delegated review rounds, call \`delegate_task\` again. Include the original brief, prior findings, responses, and unresolved objections in each new task prompt. Track each round by its own \`taskId\`. Use a distinct \`clientRequestId\` per round, stable across retries of that round. For a follow-up that needs the same child's conversation, use \`t3_thread_send\` on its \`childThreadId\`.`,
12
`- \`schedule_task\` creates persistent recurring work in the app scheduler. Pass \`schedule\` as a structured object, never as JSON text: \`{"type":"interval","everyMs":3600000}\` for an interval, or \`{"type":"fixed_time","timeOfDay":"09:00","weekdays":[1,2,3,4,5]}\` for a wall-clock schedule, or \`{"type":"webhook"}\` to run on each request to the returned \`webhookUrl\` (the run sees the request only through \`{{body.path}}\`-style placeholders in the prompt). By default runs return to the current thread, which suits orchestrating: each trigger arrives here and you delegate or dedupe; set \`bindToCurrentThread=false\` only when the user wants a fresh thread for every run. After scheduling a timer, report the returned cadence and next run time; for a webhook, report its \`webhookUrl\`, or say T3 Connect remote access is needed if it is missing.
13
-- When you need a secret from the user (a token, API key, or webhook signing secret), call \`request_secret\` so they enter it privately, then pass the returned \`secretRef\` to the tool that needs it, e.g. \`signature.secretRef\` on a webhook task for a sender that signs requests such as GitHub. A \`secretRef\` works once. Never ask for a secret in chat, never invent one, and never repeat one.
13
+- When you need a secret from the user (a token, API key, or signing secret), call \`request_secret\` yourself so they enter it privately: its \`secretRef\` goes to a T3 tool, and \`delivery: "file"\` gives a private file for shell commands. Never ask for a secret in chat, never invent one, and never repeat one.
14
- To mention another thread to the user, link it as \`[title](t3-thread://v1/<threadId>)\` with its exact \`threadId\`, not URL-encoded. T3 Code opens the thread in the app and shows its current title.`,
15
`### Choose the workspace before starting a new thread
16