+ {accessConfig[link.access].label} · {status} +
+{link.urls.join(", ")}
+ --access `.
+
+- The access you pick is the most agents from this machine may do there. An
+ agent also never gets more there than its own mode here.
+- Threads a link starts are marked **From** and this machine's name there.
+- A full-access link works there like that machine's own agents. Below full
+ access, the link's agents can change only threads it started, not that
+ machine's own threads, projects or settings, and they skip its project setup
+ scripts.
+- The link shows up in that machine's **Settings → Connections** like any
+ outside agent. Revoke it there to end it. **Forget** on this machine only
+ removes it here.
+- Links last 30 days. Link again with a new pairing code to renew one.
+
## Manage or revoke access
On the host, **Settings → Connections** lets authorized administrators create
```
## packages/client-runtime/package.json
Status: modified; +4; −0
```diff
@@ -199,6 +199,10 @@
"types": "./src/state/deviceHubAccess.ts",
"default": "./src/state/deviceHubAccess.ts"
},
+ "./state/peerLinks": {
+ "types": "./src/state/peerLinks.ts",
+ "default": "./src/state/peerLinks.ts"
+ },
"./state/preview": {
"types": "./src/state/preview.ts",
"default": "./src/state/preview.ts"
```
## packages/client-runtime/src/state/commandPermissions.test.ts
Status: modified; +132; −0
```diff
@@ -7,6 +7,8 @@
import { describe, expect, it } from "@effect/vitest";
import { vi } from "vite-plus/test";
import {
+ AuthAccessReadScope,
+ AuthAccessWriteScope,
AuthOrchestrationOperateScope,
AuthOrchestrationReadScope,
AuthPreviewOperateScope,
@@ -17,8 +19,10 @@
ScheduledTaskId,
WS_METHODS,
type AuthSessionState,
+ type PeerLinkSummary,
} from "@t3tools/contracts";
import * as Cause from "effect/Cause";
+import * as DateTime from "effect/DateTime";
import * as Effect from "effect/Effect";
import * as Fiber from "effect/Fiber";
import * as Layer from "effect/Layer";
@@ -26,6 +30,8 @@
import { EnvironmentRegistry } from "../connection/registry.ts";
import { createCommandPermissions } from "./commandPermissions.ts";
import { createEnvironmentRpcCommand } from "./runtime.ts";
+import { AVAILABLE_CONNECTION_STATE } from "../connection/model.ts";
+import { createPeerLinkEnvironmentAtoms } from "./peerLinks.ts";
vi.mock("./session.ts", () => ({
createEnvironmentSessionAtoms: () => ({ sessionStateAtom: sessions }),
@@ -291,6 +297,132 @@
),
);
+it.effect(
+ "refreshes linked environments after permitted writes and blocks a read-only session",
+ () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const registry = yield* setup;
+ const peer: PeerLinkSummary = {
+ environmentId: EnvironmentId.make("peer"),
+ label: "Box",
+ urls: ["https://box.example.test"],
+ access: "auto",
+ linkedAt: DateTime.makeUnsafe("2026-10-01T12:00:00Z"),
+ expiresAt: DateTime.makeUnsafe("2026-10-31T12:00:00Z"),
+ lastReachedAt: null,
+ lastError: null,
+ status: "reachable",
+ };
+ let links: ReadonlyArray = [];
+ const client = {
+ [WS_METHODS.peerLinksList]: () => Effect.sync(() => ({ links })),
+ [WS_METHODS.peerLinksLink]: vi.fn(() =>
+ Effect.sync(() => {
+ links = [peer];
+ return peer;
+ }),
+ ),
+ [WS_METHODS.peerLinksUnlink]: vi.fn(() =>
+ Effect.sync(() => {
+ links = [];
+ return { removed: true };
+ }),
+ ),
+ };
+ const supervisor = {
+ target: { environmentId: env },
+ session: yield* SubscriptionRef.make(Option.some({ client } as unknown as RpcSession)),
+ state: yield* SubscriptionRef.make({
+ ...AVAILABLE_CONNECTION_STATE,
+ phase: "connected" as const,
+ }),
+ } as EnvironmentSupervisor["Service"];
+ const peerRuntime = Atom.runtime(
+ Layer.succeed(EnvironmentRegistry, {
+ run: (id, effect) => {
+ expect(id).toBe(env);
+ return Effect.provideService(effect, EnvironmentSupervisor, supervisor);
+ },
+ followStream: (id, stream) => {
+ expect(id).toBe(env);
+ return Stream.provideService(stream, EnvironmentSupervisor, supervisor);
+ },
+ } as EnvironmentRegistry["Service"]),
+ );
+ const peerLinks = createPeerLinkEnvironmentAtoms(peerRuntime);
+ const list = peerLinks.list({ environmentId: env, input: {} });
+ registry.mount(list);
+ const readLinks = AtomRegistry.getResult(registry, list, { suspendOnWaiting: true });
+ const setAccess = (writable: boolean) =>
+ registry.set(
+ sessions(env),
+ AsyncResult.success({
+ ...grant(false),
+ scopes: [AuthAccessReadScope, ...(writable ? [AuthAccessWriteScope] : [])],
+ permissions: [AuthAccessReadScope, ...(writable ? [AuthAccessWriteScope] : [])],
+ }),
+ );
+ registry.mount(sessions(other));
+ registry.set(
+ sessions(other),
+ AsyncResult.success({
+ ...grant(false),
+ scopes: [AuthAccessWriteScope],
+ permissions: [AuthAccessWriteScope],
+ }),
+ );
+ setAccess(false);
+ expect(yield* readLinks).toEqual({ links: [] });
+ const linkInput = { url: peer.urls[0]!, pairingCode: "test-code", access: peer.access };
+ const link = Effect.promise(() =>
+ peerLinks.link.run(registry, { environmentId: env, input: linkInput }),
+ );
+ const unlink = Effect.promise(() =>
+ peerLinks.unlink.run(registry, {
+ environmentId: env,
+ input: { environmentId: peer.environmentId },
+ }),
+ );
+ expect(registry.get(peerLinks.link.permissionAtom(env))).toBe(false);
+ const deniedLink = yield* link;
+ expect(deniedLink._tag).toBe("Failure");
+ if (deniedLink._tag === "Failure") {
+ expect(Cause.squash(deniedLink.cause)).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredPermission: AuthAccessWriteScope,
+ });
+ }
+ expect(client[WS_METHODS.peerLinksLink]).not.toHaveBeenCalled();
+ setAccess(true);
+ expect(registry.get(peerLinks.link.permissionAtom(env))).toBe(true);
+ expect((yield* link)._tag).toBe("Success");
+ expect(client[WS_METHODS.peerLinksLink]).toHaveBeenCalledExactlyOnceWith(linkInput);
+ expect(yield* readLinks).toEqual({ links: [peer] });
+
+ setAccess(false);
+ expect(registry.get(peerLinks.unlink.permissionAtom(env))).toBe(false);
+ const deniedUnlink = yield* unlink;
+ expect(deniedUnlink._tag).toBe("Failure");
+ if (deniedUnlink._tag === "Failure") {
+ expect(Cause.squash(deniedUnlink.cause)).toMatchObject({
+ _tag: "EnvironmentAuthorizationError",
+ requiredPermission: AuthAccessWriteScope,
+ });
+ }
+ expect(client[WS_METHODS.peerLinksUnlink]).not.toHaveBeenCalled();
+ expect(yield* readLinks).toEqual({ links: [peer] });
+ setAccess(true);
+ expect(registry.get(peerLinks.unlink.permissionAtom(env))).toBe(true);
+ expect((yield* unlink)._tag).toBe("Success");
+ expect(client[WS_METHODS.peerLinksUnlink]).toHaveBeenCalledExactlyOnceWith({
+ environmentId: peer.environmentId,
+ });
+ expect(yield* readLinks).toEqual({ links: [] });
+ }),
+ ),
+);
+
it.effect("honors exact empty permissions and preserves legacy parent grants", () =>
Effect.scoped(
Effect.gen(function* () {
```
## packages/client-runtime/src/state/models.ts
Status: modified; +2; −0
```diff
@@ -100,6 +100,7 @@
readonly worktreePath: string | null;
readonly lineage: OrchestrationV2ThreadShell["lineage"];
readonly forkedFrom: OrchestrationV2ThreadShell["forkedFrom"];
+ readonly linkOrigin: OrchestrationV2ThreadShell["linkOrigin"] | null;
readonly activeProviderThreadId: OrchestrationV2ThreadShell["activeProviderThreadId"];
readonly latestRun: ThreadRunSummary | null;
readonly runtime: ThreadRuntimeSummary | null;
@@ -246,6 +247,7 @@
branchPullRequest: thread.branchPullRequest ?? null,
lineage: thread.lineage,
forkedFrom: thread.forkedFrom,
+ linkOrigin: thread.linkOrigin ?? null,
activeProviderThreadId: thread.activeProviderThreadId,
latestRun,
runtime,
```
## packages/client-runtime/src/state/peerLinks.ts
Status: added; +57; −0
```diff
@@ -1,0 +1,57 @@
+import { type PeerLinkSummary, WS_METHODS } from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { Atom } from "effect/reactivity";
+
+import type { EnvironmentRegistry } from "../connection/registry.ts";
+import { createEnvironmentRpcCommand, createEnvironmentRpcQueryAtomFamily } from "./runtime.ts";
+
+export function createPeerLinkEnvironmentAtoms(
+ runtime: Atom.AtomRuntime,
+) {
+ const list = createEnvironmentRpcQueryAtomFamily(runtime, {
+ label: "environment-data:peer-links:list",
+ tag: WS_METHODS.peerLinksList,
+ // Listing probes every linked environment, so a list stays fresh briefly.
+ staleTimeMs: 10_000,
+ });
+ return {
+ list,
+ link: createEnvironmentRpcCommand(runtime, {
+ label: "environment-data:peer-links:link",
+ tag: WS_METHODS.peerLinksLink,
+ onSuccess: ({ environmentId }, registry) =>
+ Effect.sync(() => registry.refresh(list({ environmentId, input: {} }))),
+ }),
+ unlink: createEnvironmentRpcCommand(runtime, {
+ label: "environment-data:peer-links:unlink",
+ tag: WS_METHODS.peerLinksUnlink,
+ onSuccess: ({ environmentId }, registry) =>
+ Effect.sync(() => registry.refresh(list({ environmentId, input: {} }))),
+ }),
+ };
+}
+
+const EXPIRY_WARNING_DAYS = 5;
+
+export type PeerLinkHealth =
+ | { readonly kind: "reachable"; readonly expiresInDays: number | null }
+ | { readonly kind: "unreachable"; readonly detail: string | null }
+ | { readonly kind: "failing"; readonly detail: string }
+ | { readonly kind: "expired" };
+
+/**
+ * Listing only checks that the peer answers, so a link whose last call failed
+ * (the peer revoked it, say) is `failing` with the recorded reason; the next
+ * successful call clears it.
+ */
+export function peerLinkHealth(link: PeerLinkSummary, now: DateTime.Utc): PeerLinkHealth {
+ if (link.status === "expired" || DateTime.isLessThanOrEqualTo(link.expiresAt, now)) {
+ return { kind: "expired" };
+ }
+ if (link.status === "unreachable") return { kind: "unreachable", detail: link.lastError };
+ if (link.lastError !== null) return { kind: "failing", detail: link.lastError };
+ const days = Math.ceil(Duration.toDays(DateTime.distance(now, link.expiresAt)));
+ return { kind: "reachable", expiresInDays: days <= EXPIRY_WARNING_DAYS ? days : null };
+}
```
## packages/contracts/src/clientRpcPermissions.ts
Status: modified; +4; −0
```diff
@@ -1,6 +1,7 @@
import * as Schema from "effect/Schema";
import { GitPreparePullRequestThreadInput, GitRunStackedActionInput } from "./git.ts";
import {
+ AuthAccessWriteScope,
AuthOrchestrationOperateScope,
AuthOrchestrationReadScope,
AuthPreviewOperateScope,
@@ -49,6 +50,9 @@
[WS_METHODS.scheduledTasksRunNow]: AuthOrchestrationOperateScope,
[WS_METHODS.scheduledTasksRotateWebhookToken]: AuthOrchestrationOperateScope,
[ORCHESTRATION_V2_WS_METHODS.stopWorkflow]: AuthOrchestrationOperateScope,
+
+ [WS_METHODS.peerLinksLink]: AuthAccessWriteScope,
+ [WS_METHODS.peerLinksUnlink]: AuthAccessWriteScope,
} as const;
export type ClientGuardedRpcTag = keyof typeof CLIENT_GUARDED_RPC_SCOPES;
```