feat: agents know where you are and where the dev server runs

AGENTS.md

@@ -79,7 +79,8 @@ The most common defect in this repo is a change that works on the path you teste
 
 - `vp i` installs. Worktrees get this from the t3.json setup script; if module resolution looks broken, it probably did not run.
 - `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.
-- 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.
+- 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.
+- User messages can start with `<sent_from>`, which says where the user is. Give a remote user tailnet (`--share`) links, not localhost.
 - 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.
 - 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).
 - Stop what you started, by the PID you tracked. See rule 1.

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

@@ -4076,6 +4076,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
     readonly creationSource: OrchestrationV2ConversationMessage["creationSource"];
     readonly scheduledTaskId?: OrchestrationV2ConversationMessage["scheduledTaskId"];
     readonly senderThreadId?: OrchestrationV2ConversationMessage["senderThreadId"];
+    readonly sentFrom?: OrchestrationV2ConversationMessage["sentFrom"];
     readonly delegatedCompletion?: OrchestrationV2ConversationMessage["delegatedCompletion"];
     readonly forceRestart: boolean;
   }) {
@@ -4233,6 +4234,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
             ? {}
             : { scheduledTaskId: input.scheduledTaskId }),
           ...(input.senderThreadId === undefined ? {} : { senderThreadId: input.senderThreadId }),
+          ...(input.sentFrom === undefined ? {} : { sentFrom: input.sentFrom }),
           id: input.messageId,
           threadId: input.command.threadId,
           runId: messageInput.runId,
@@ -5183,6 +5185,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
           ? {}
           : { scheduledTaskId: command.scheduledTaskId }),
         ...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
+        ...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
         forceRestart: dispatchMode.type === "restart_active",
       });
       return;
@@ -5418,6 +5421,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
           ? {}
           : { scheduledTaskId: command.scheduledTaskId }),
         ...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
+        ...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
         id: command.messageId,
         threadId: command.threadId,
         runId,
@@ -5758,6 +5762,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
           ? {}
           : { scheduledTaskId: command.scheduledTaskId }),
         ...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
+        ...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
         id: command.messageId,
         threadId: command.threadId,
         runId,
@@ -6445,6 +6450,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
         ? {}
         : { scheduledTaskId: command.scheduledTaskId }),
       ...(command.senderThreadId === undefined ? {} : { senderThreadId: command.senderThreadId }),
+      ...(command.sentFrom === undefined ? {} : { sentFrom: command.sentFrom }),
       id: command.messageId,
       threadId: command.threadId,
       runId,
@@ -8014,6 +8020,7 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
       ...(queuedMessage.senderThreadId === undefined
         ? {}
         : { senderThreadId: queuedMessage.senderThreadId }),
+      ...(queuedMessage.sentFrom === undefined ? {} : { sentFrom: queuedMessage.sentFrom }),
       forceRestart: false,
     });
   });

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

@@ -53,6 +53,7 @@ import {
 } from "@t3tools/provider-core/server/failure";
 import * as RunExecutionService from "./RunExecutionService.ts";
 import * as RuntimePolicy from "./RuntimePolicy.ts";
+import { formatSentFromContext } from "./sentFromContext.ts";
 import {
   isRestartNoteContinuation,
   pendingRestartCancelledBackgroundWork,
@@ -954,10 +955,15 @@ export const layer: Layer.Layer<
       const routableSubagents = projection.subagents.filter((subagent) =>
         RunExecutionService.canRouteRelatedSubagent(subagent.status),
       );
-      const userText = projectComposerContextForProvider({
+      const promptText = projectComposerContextForProvider({
         text: message.text,
         records: message.context?.records ?? [],
       });
+      // Adapters run slash commands (`/compact`, skills) only from the start of the text.
+      const userText =
+        message.sentFrom === undefined || promptText.trimStart().startsWith("/")
+          ? promptText
+          : `${formatSentFromContext(message.sentFrom)}\n\n${promptText}`;
       // Delivered once: this run's provider turn marks the work as told. A
       // restart continuation is prompted by its own text or resumes natively.
       const noteContinuation = isRestartNoteContinuation(

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

@@ -9,6 +9,7 @@ import {
   type ModelSelection,
   type OrchestrationV2Actor,
   type OrchestrationV2CreationSource,
+  type OrchestrationV2MessageSentFrom,
   type OrchestrationV2ProviderThreadNativeMetadata,
   type OrchestrationV2ThreadProjection,
   type ProviderDriverKind,
@@ -69,6 +70,7 @@ export interface ThreadLaunchInitialMessage {
   readonly messageId?: MessageId;
   readonly scheduledTaskId?: ScheduledTaskId;
   readonly senderThreadId?: ThreadId;
+  readonly sentFrom?: OrchestrationV2MessageSentFrom;
   readonly text: string;
   readonly attachments: ReadonlyArray<ChatAttachment>;
   readonly context?: import("@t3tools/contracts").OrchestrationMessageContext | undefined;
@@ -965,6 +967,9 @@ const make = Effect.gen(function* () {
               ...(input.initialMessage.senderThreadId === undefined
                 ? {}
                 : { senderThreadId: input.initialMessage.senderThreadId }),
+              ...(input.initialMessage.sentFrom === undefined
+                ? {}
+                : { sentFrom: input.initialMessage.sentFrom }),
               attachments: input.initialMessage.attachments,
               ...(input.initialMessage.context ? { context: input.initialMessage.context } : {}),
               ...(input.generateTitle === true ? { titleSeed: input.title } : {}),

apps/server/src/orchestration-v2/sentFromContext.test.ts

@@ -0,0 +1,34 @@
+import { assert, describe, it } from "@effect/vitest";
+
+import { formatSentFromContext } from "./sentFromContext.ts";
+
+describe("formatSentFromContext", () => {
+  it("says localhost works when the client dialed loopback directly", () => {
+    assert.equal(
+      formatSentFromContext({
+        surface: "desktop",
+        os: "macOS",
+        connectionMethod: "direct",
+        host: "127.0.0.1:3773",
+        serverLabel: "Mainbook",
+      }),
+      "<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>",
+    );
+  });
+
+  it("points at the dialed name when the client is elsewhere on the network", () => {
+    assert.include(
+      formatSentFromContext({ surface: "web", host: "mainbook.example.ts.net:5733" }),
+      "Use mainbook.example.ts.net instead of localhost",
+    );
+  });
+
+  // T3 Connect and SSH tunnels arrive on loopback, so the host alone would mislead.
+  it("does not trust a loopback host behind a relay or tunnel", () => {
+    for (const connectionMethod of ["relay", "ssh"] as const) {
+      const text = formatSentFromContext({ connectionMethod, host: "127.0.0.1:3773" });
+      assert.include(text, "probably not at this machine");
+      assert.notInclude(text, "127.0.0.1");
+    }
+  });
+});

apps/server/src/orchestration-v2/sentFromContext.ts

@@ -0,0 +1,52 @@
+import type { OrchestrationV2MessageSentFrom } from "@t3tools/contracts";
+
+const CLIENT_NAMES = {
+  desktop: "the T3 Code desktop app",
+  web: "a web browser",
+  mobile: "the T3 Code mobile app",
+  cli: "the T3 Code CLI",
+} as const;
+
+const LOOPBACK_HOSTNAME = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/i;
+
+function hostnameOf(host: string): string {
+  return host.startsWith("[") ? host.slice(0, host.indexOf("]") + 1) : host.replace(/:\d+$/, "");
+}
+
+// Relay and SSH tunnels reach the server on loopback, so their route decides
+// before the dialed host can.
+function reachSentence(sentFrom: OrchestrationV2MessageSentFrom): string {
+  if (sentFrom.connectionMethod === "relay" || sentFrom.connectionMethod === "ssh") {
+    return " The user is probably not at this machine, so localhost URLs do not work for them.";
+  }
+  if (sentFrom.host === undefined) return "";
+  const hostname = hostnameOf(sentFrom.host);
+  return LOOPBACK_HOSTNAME.test(hostname)
+    ? " The user is at this machine, so localhost URLs work for them."
+    : ` The user is not at this machine. Use ${hostname} instead of localhost in URLs you give them.`;
+}
+
+/**
+ * Tells the agent where the user is, so links it gives (dev servers, previews)
+ * work from the user's device and "this machine" means the right one.
+ */
+export function formatSentFromContext(sentFrom: OrchestrationV2MessageSentFrom): string {
+  const client =
+    sentFrom.surface === undefined ? "a T3 Code client" : CLIENT_NAMES[sentFrom.surface];
+  const os = sentFrom.os === undefined || sentFrom.os === "other" ? "" : ` on ${sentFrom.os}`;
+  const device =
+    sentFrom.deviceType === "phone" || sentFrom.deviceType === "tablet"
+      ? ` (${sentFrom.deviceType})`
+      : "";
+  const machine =
+    sentFrom.serverLabel === undefined ? "this machine" : `this machine (${sentFrom.serverLabel})`;
+  const route =
+    sentFrom.connectionMethod === "relay"
+      ? " through T3 Connect"
+      : sentFrom.connectionMethod === "ssh"
+        ? " through an SSH tunnel"
+        : sentFrom.host === undefined
+          ? ""
+          : ` at ${sentFrom.host}`;
+  return `<sent_from>The user sent this message from ${client}${os}${device} to ${machine}${route}.${reachSentence(sentFrom)}</sent_from>`;
+}

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

@@ -18,6 +18,7 @@ import { TestClock } from "effect/testing";
 
 import * as EffectWorker from "../EffectWorker.ts";
 import * as Orchestrator from "../Orchestrator.ts";
+import { formatSentFromContext } from "../sentFromContext.ts";
 
 import { ClaudeOrchestratorReplayHarness } from "../Adapters/ClaudeAdapterV2.testkit.ts";
 import { CodexOrchestratorReplayHarness } from "../Adapters/CodexAdapterV2.testkit.ts";
@@ -486,6 +487,61 @@ describe("orchestrator replay fixtures", () => {
       }),
   );
 
+  const simpleFixture = ORCHESTRATOR_REPLAY_FIXTURES.find(
+    (candidate) => candidate.name === "simple",
+  );
+  const simpleClaude = simpleFixture?.providers.find(
+    (provider) => provider.driver === "claudeAgent",
+  );
+  if (simpleFixture !== undefined && simpleClaude !== undefined) {
+    it.effect("tells the provider where a client-sent message came from", () => {
+      const sentFrom = {
+        surface: "mobile",
+        os: "iOS",
+        deviceType: "phone",
+        connectionMethod: "relay",
+        host: "127.0.0.1:3773",
+        serverLabel: "Mainbook",
+      } as const;
+      const prompted = `${formatSentFromContext(sentFrom)}\n\n${SIMPLE_PROMPT}`;
+      return runFixtureProviderWithRegisteredHarness({
+        fixtureName: simpleFixture.name,
+        buildInput: () => ({ steps: [{ type: "message", text: SIMPLE_PROMPT, sentFrom }] }),
+        driver: {
+          ...simpleClaude,
+          assertOutput: (result, transcript) => {
+            simpleClaude.assertOutput(result, transcript);
+            const message = projectionFor(result, simpleFixture.name).messages.find(
+              (candidate) => candidate.role === "user",
+            );
+            // The thread shows what the user typed; only the provider sees the context.
+            assert.equal(message?.text, SIMPLE_PROMPT);
+            assert.deepEqual(message?.sentFrom, sentFrom);
+          },
+        },
+        // The replay fails unless the adapter sends exactly this prompt.
+        transformTranscript: (transcript) => ({
+          ...transcript,
+          entries: transcript.entries.map((entry) =>
+            entry.type === "expect_outbound" && entry.label === "prompt.offer:1"
+              ? {
+                  ...entry,
+                  frame: {
+                    type: "prompt.offer",
+                    message: {
+                      type: "user",
+                      message: { role: "user", content: prompted },
+                      parent_tool_use_id: null,
+                    },
+                  },
+                }
+              : entry,
+          ),
+        }),
+      });
+    });
+  }
+
   const afterRootFixture = ORCHESTRATOR_REPLAY_FIXTURES.find(
     (candidate) => candidate.name === "claude_background_subagent_after_root",
   );