Skip to content

Commit 40f36fd

Browse files
t3dotggclaude
andcommitted
feat: tell agents where the user is and where the dev server runs
User messages from clients now carry a server-stamped sentFrom (client surface, OS, device, connection method, dialed host, machine label). Turn start puts a one-line <sent_from> note ahead of the prompt so agents pick localhost or tailnet links correctly. runtime_info gains a hint that bare UUIDs are T3 thread IDs. The dev runner writes <T3 home>/dev-runner.json with ports, URLs, and reusable-token pairing links. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent d18352e commit 40f36fd

35 files changed

Lines changed: 504 additions & 105 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,8 @@ The most common defect in this repo is a change that works on the path you teste
7979

8080
- `vp i` installs. Worktrees get this from the t3.json setup script; if module resolution looks broken, it probably did not run.
8181
- `vp run dev` starts server and web. In a worktree, state defaults to that worktree's gitignored `.t3`, which deliberately outranks an ambient `T3CODE_HOME` so you cannot land on shared state by accident. An explicit `--home-dir` still wins.
82-
- Ports derive from the worktree path and are stable across restarts, but read the real ones from the `[dev-runner]` line since occupied ports shift.
82+
- Ports derive from the worktree path and are stable across restarts, but occupied ports shift. While the runner is up, read the real ports and URLs from `.t3/dev-runner.json` (in the T3 home, so `--home-dir` moves it) instead of polling the log. Its `pid` tells you whether the runner is still alive; signalling only that PID leaves Vite and the server running. It also holds pairing URLs when a reusable dev token is set. Those URLs are admin credentials: give them only to the user.
83+
- User messages can start with `<sent_from>`, which says where the user is. Give a remote user tailnet (`--share`) links, not localhost.
8384
- Sharing over the tailnet is three steps: run `vp run dev --share` in the background, wait for the `pairingUrl:` line in its output, then give that full URL to an unpaired browser. Do not wire up `tailscale serve` by hand, open the URL yourself, or consume the user's pairing link. A browser with the reusable dev cookie can use the bare origin. If a normal one-time token was consumed, mint a fresh one with `node apps/server/src/bin.ts pair`. It carries standard scopes, while the startup URL carries admin scopes needed for Connections settings.
8485
- To reuse web dev auth across worktrees, configure one fixed `T3CODE_DEV_AUTH_TOKEN` in the main checkout's gitignored `.env`. The `t3.json` setup links that file into worktrees. Never commit or publish the token or a startup URL. See [Reusable dev credential](docs/operations/development.md#reusable-dev-credential).
8586
- Stop what you started, by the PID you tracked. See rule 1.

‎apps/server/src/orchestration-v2/Orchestrator.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4076,6 +4076,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
40764076
readonly creationSource: OrchestrationV2ConversationMessage["creationSource"];
40774077
readonly scheduledTaskId?: OrchestrationV2ConversationMessage["scheduledTaskId"];
40784078
readonly senderThreadId?: OrchestrationV2ConversationMessage["senderThreadId"];
4079+
readonly sentFrom?: OrchestrationV2ConversationMessage["sentFrom"];
40794080
readonly delegatedCompletion?: OrchestrationV2ConversationMessage["delegatedCompletion"];
40804081
readonly forceRestart: boolean;
40814082
}) {
@@ -4233,6 +4234,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
42334234
? {}
42344235
: { scheduledTaskId: input.scheduledTaskId }),
42354236
...(input.senderThreadId === undefined ? {} : { senderThreadId: input.senderThreadId }),
4237+
...(input.sentFrom === undefined ? {} : { sentFrom: input.sentFrom }),
42364238
id: input.messageId,
42374239
threadId: input.command.threadId,
42384240
runId: messageInput.runId,
@@ -5183,6 +5185,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
51835185
? {}
51845186
: { scheduledTaskId: command.scheduledTaskId }),
51855187
...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
5188+
...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
51865189
forceRestart: dispatchMode.type === "restart_active",
51875190
});
51885191
return;
@@ -5418,6 +5421,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
54185421
? {}
54195422
: { scheduledTaskId: command.scheduledTaskId }),
54205423
...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
5424+
...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
54215425
id: command.messageId,
54225426
threadId: command.threadId,
54235427
runId,
@@ -5758,6 +5762,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
57585762
? {}
57595763
: { scheduledTaskId: command.scheduledTaskId }),
57605764
...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
5765+
...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
57615766
id: command.messageId,
57625767
threadId: command.threadId,
57635768
runId,
@@ -6445,6 +6450,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
64456450
? {}
64466451
: { scheduledTaskId: command.scheduledTaskId }),
64476452
...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
6453+
...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
64486454
id: command.messageId,
64496455
threadId: command.threadId,
64506456
runId,
@@ -8014,6 +8020,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
80148020
...(queuedMessage.senderThreadId === undefined
80158021
? {}
80168022
: { senderThreadId: queuedMessage.senderThreadId }),
8023+
...(queuedMessage.sentFrom === undefined ? {} : { sentFrom: queuedMessage.sentFrom }),
80178024
forceRestart: false,
80188025
});
80198026
});

‎apps/server/src/orchestration-v2/ProviderTurnStartService.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ import {
5353
} from "@t3tools/provider-core/server/failure";
5454
import * as RunExecutionService from "./RunExecutionService.ts";
5555
import * as RuntimePolicy from "./RuntimePolicy.ts";
56+
import { formatSentFromContext } from "./sentFromContext.ts";
5657
import {
5758
isRestartNoteContinuation,
5859
pendingRestartCancelledBackgroundWork,
@@ -954,10 +955,15 @@ export const layer: Layer.Layer<
954955
const routableSubagents = projection.subagents.filter((subagent) =>
955956
RunExecutionService.canRouteRelatedSubagent(subagent.status),
956957
);
957-
const userText = projectComposerContextForProvider({
958+
const promptText = projectComposerContextForProvider({
958959
text: message.text,
959960
records: message.context?.records ?? [],
960961
});
962+
// Adapters run slash commands (`/compact`, skills) only from the start of the text.
963+
const userText =
964+
message.sentFrom === undefined || promptText.trimStart().startsWith("/")
965+
? promptText
966+
: `${formatSentFromContext(message.sentFrom)}\n\n${promptText}`;
961967
// Delivered once: this run's provider turn marks the work as told. A
962968
// restart continuation is prompted by its own text or resumes natively.
963969
const noteContinuation = isRestartNoteContinuation(

‎apps/server/src/orchestration-v2/ThreadLaunchService.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
type ModelSelection,
1010
type OrchestrationV2Actor,
1111
type OrchestrationV2CreationSource,
12+
type OrchestrationV2MessageSentFrom,
1213
type OrchestrationV2ProviderThreadNativeMetadata,
1314
type OrchestrationV2ThreadProjection,
1415
type ProviderDriverKind,
@@ -69,6 +70,7 @@ export interface ThreadLaunchInitialMessage {
6970
readonly messageId?: MessageId;
7071
readonly scheduledTaskId?: ScheduledTaskId;
7172
readonly senderThreadId?: ThreadId;
73+
readonly sentFrom?: OrchestrationV2MessageSentFrom;
7274
readonly text: string;
7375
readonly attachments: ReadonlyArray<ChatAttachment>;
7476
readonly context?: import("@t3tools/contracts").OrchestrationMessageContext | undefined;
@@ -965,6 +967,9 @@ const make = Effect.gen(function* () {
965967
...(input.initialMessage.senderThreadId === undefined
966968
? {}
967969
: { senderThreadId: input.initialMessage.senderThreadId }),
970+
...(input.initialMessage.sentFrom === undefined
971+
? {}
972+
: { sentFrom: input.initialMessage.sentFrom }),
968973
attachments: input.initialMessage.attachments,
969974
...(input.initialMessage.context ? { context: input.initialMessage.context } : {}),
970975
...(input.generateTitle === true ? { titleSeed: input.title } : {}),
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import { assert, describe, it } from "@effect/vitest";
2+
3+
import { formatSentFromContext } from "./sentFromContext.ts";
4+
5+
describe("formatSentFromContext", () => {
6+
it("says localhost works when the client dialed loopback directly", () => {
7+
assert.equal(
8+
formatSentFromContext({
9+
surface: "desktop",
10+
os: "macOS",
11+
connectionMethod: "direct",
12+
host: "127.0.0.1:3773",
13+
serverLabel: "Mainbook",
14+
}),
15+
"<sent_from>The user sent this message from the T3 Code desktop app on macOS to this machine (Mainbook) at 127.0.0.1:3773. The user is at this machine, so localhost URLs work for them.</sent_from>",
16+
);
17+
});
18+
19+
it("points at the dialed name when the client is elsewhere on the network", () => {
20+
assert.include(
21+
formatSentFromContext({ surface: "web", host: "mainbook.example.ts.net:5733" }),
22+
"Use mainbook.example.ts.net instead of localhost",
23+
);
24+
});
25+
26+
// T3 Connect and SSH tunnels arrive on loopback, so the host alone would mislead.
27+
it("does not trust a loopback host behind a relay or tunnel", () => {
28+
for (const connectionMethod of ["relay", "ssh"] as const) {
29+
const text = formatSentFromContext({ connectionMethod, host: "127.0.0.1:3773" });
30+
assert.include(text, "probably not at this machine");
31+
assert.notInclude(text, "127.0.0.1");
32+
}
33+
});
34+
});
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import type { OrchestrationV2MessageSentFrom } from "@t3tools/contracts";
2+
3+
const CLIENT_NAMES = {
4+
desktop: "the T3 Code desktop app",
5+
web: "a web browser",
6+
mobile: "the T3 Code mobile app",
7+
cli: "the T3 Code CLI",
8+
} as const;
9+
10+
const LOOPBACK_HOSTNAME = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/i;
11+
12+
function hostnameOf(host: string): string {
13+
return host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.replace(/:\d+$/, "");
14+
}
15+
16+
// Relay and SSH tunnels reach the server on loopback, so their route decides
17+
// before the dialed host can.
18+
function reachSentence(sentFrom: OrchestrationV2MessageSentFrom): string {
19+
if (sentFrom.connectionMethod === "relay" || sentFrom.connectionMethod === "ssh") {
20+
return " The user is probably not at this machine, so localhost URLs do not work for them.";
21+
}
22+
if (sentFrom.host === undefined) return "";
23+
const hostname = hostnameOf(sentFrom.host);
24+
return LOOPBACK_HOSTNAME.test(hostname)
25+
? " The user is at this machine, so localhost URLs work for them."
26+
: ` The user is not at this machine. Use ${hostname} instead of localhost in URLs you give them.`;
27+
}
28+
29+
/**
30+
* Tells the agent where the user is, so links it gives (dev servers, previews)
31+
* work from the user's device and "this machine" means the right one.
32+
*/
33+
export function formatSentFromContext(sentFrom: OrchestrationV2MessageSentFrom): string {
34+
const client =
35+
sentFrom.surface === undefined ? "a T3 Code client" : CLIENT_NAMES[sentFrom.surface];
36+
const os = sentFrom.os === undefined || sentFrom.os === "other" ? "" : ` on ${sentFrom.os}`;
37+
const device =
38+
sentFrom.deviceType === "phone" || sentFrom.deviceType === "tablet"
39+
? ` (${sentFrom.deviceType})`
40+
: "";
41+
const machine =
42+
sentFrom.serverLabel === undefined ? "this machine" : `this machine (${sentFrom.serverLabel})`;
43+
const route =
44+
sentFrom.connectionMethod === "relay"
45+
? " through T3 Connect"
46+
: sentFrom.connectionMethod === "ssh"
47+
? " through an SSH tunnel"
48+
: sentFrom.host === undefined
49+
? ""
50+
: ` at ${sentFrom.host}`;
51+
return `<sent_from>The user sent this message from ${client}${os}${device} to ${machine}${route}.${reachSentence(sentFrom)}</sent_from>`;
52+
}

‎apps/server/src/orchestration-v2/testkit/OrchestratorReplayFixtures.integration.test.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import { TestClock } from "effect/testing";
1818

1919
import * as EffectWorker from "../EffectWorker.ts";
2020
import * as Orchestrator from "../Orchestrator.ts";
21+
import { formatSentFromContext } from "../sentFromContext.ts";
2122

2223
import { ClaudeOrchestratorReplayHarness } from "../Adapters/ClaudeAdapterV2.testkit.ts";
2324
import { CodexOrchestratorReplayHarness } from "../Adapters/CodexAdapterV2.testkit.ts";
@@ -486,6 +487,61 @@ describe("orchestrator replay fixtures", () => {
486487
}),
487488
);
488489

490+
const simpleFixture = ORCHESTRATOR_REPLAY_FIXTURES.find(
491+
(candidate) => candidate.name === "simple",
492+
);
493+
const simpleClaude = simpleFixture?.providers.find(
494+
(provider) => provider.driver === "claudeAgent",
495+
);
496+
if (simpleFixture !== undefined && simpleClaude !== undefined) {
497+
it.effect("tells the provider where a client-sent message came from", () => {
498+
const sentFrom = {
499+
surface: "mobile",
500+
os: "iOS",
501+
deviceType: "phone",
502+
connectionMethod: "relay",
503+
host: "127.0.0.1:3773",
504+
serverLabel: "Mainbook",
505+
} as const;
506+
const prompted = `${formatSentFromContext(sentFrom)}\n\n${SIMPLE_PROMPT}`;
507+
return runFixtureProviderWithRegisteredHarness({
508+
fixtureName: simpleFixture.name,
509+
buildInput: () => ({ steps: [{ type: "message", text: SIMPLE_PROMPT, sentFrom }] }),
510+
driver: {
511+
...simpleClaude,
512+
assertOutput: (result, transcript) => {
513+
simpleClaude.assertOutput(result, transcript);
514+
const message = projectionFor(result, simpleFixture.name).messages.find(
515+
(candidate) => candidate.role === "user",
516+
);
517+
// The thread shows what the user typed; only the provider sees the context.
518+
assert.equal(message?.text, SIMPLE_PROMPT);
519+
assert.deepEqual(message?.sentFrom, sentFrom);
520+
},
521+
},
522+
// The replay fails unless the adapter sends exactly this prompt.
523+
transformTranscript: (transcript) => ({
524+
...transcript,
525+
entries: transcript.entries.map((entry) =>
526+
entry.type === "expect_outbound" && entry.label === "prompt.offer:1"
527+
? {
528+
...entry,
529+
frame: {
530+
type: "prompt.offer",
531+
message: {
532+
type: "user",
533+
message: { role: "user", content: prompted },
534+
parent_tool_use_id: null,
535+
},
536+
},
537+
}
538+
: entry,
539+
),
540+
}),
541+
});
542+
});
543+
}
544+
489545
const afterRootFixture = ORCHESTRATOR_REPLAY_FIXTURES.find(
490546
(candidate) => candidate.name === "claude_background_subagent_after_root",
491547
);

0 commit comments

Comments
 (0)