@devries-cameron20 / t3code Mirror · read-only / commits / e0b194021b
Fork 0

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