Skip to content

Commit d8fac27

Browse files
committed
feat(threads): add agent-requested handoffs
1 parent bad1143 commit d8fac27

28 files changed

Lines changed: 1890 additions & 72 deletions

‎apps/mobile/src/features/threads/ThreadDetailScreen.tsx‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import type {
1414
RuntimeMode,
1515
ServerConfig as T3ServerConfig,
1616
ThreadId,
17+
ThreadHandoff,
1718
UserInputQuestion,
1819
} from "@t3tools/contracts";
1920
import * as Haptics from "expo-haptics";
@@ -77,6 +78,7 @@ import {
7778
ThreadComposer,
7879
} from "./ThreadComposer";
7980
import { ThreadFeed } from "./ThreadFeed";
81+
import { ThreadHandoffCard } from "./ThreadHandoffCard";
8082
import type { ThreadContentPresentation } from "./threadContentPresentation";
8183

8284
export interface ThreadDetailScreenProps {
@@ -136,6 +138,10 @@ export interface ThreadDetailScreenProps {
136138
) => void;
137139
readonly onSubmitUserInput: () => Promise<unknown>;
138140
readonly showContent?: boolean;
141+
readonly availableHandoffs?: ReadonlyArray<ThreadHandoff>;
142+
readonly handoffActionId?: string | null;
143+
readonly onOpenHandoff?: (handoff: ThreadHandoff) => void;
144+
readonly onDismissHandoff?: (handoff: ThreadHandoff) => void;
139145
}
140146

141147
function latestStreamingAssistantMessage(
@@ -581,6 +587,15 @@ export const ThreadDetailScreen = memo(function ThreadDetailScreen(props: Thread
581587
onTouchEnd={handleFeedTouchEnd}
582588
onTouchCancel={handleFeedTouchCancel}
583589
>
590+
{props.availableHandoffs?.map((handoff) => (
591+
<ThreadHandoffCard
592+
key={handoff.handoffId}
593+
handoff={handoff}
594+
busy={props.handoffActionId !== null && props.handoffActionId !== undefined}
595+
onOpen={() => props.onOpenHandoff?.(handoff)}
596+
onDismiss={() => props.onDismissHandoff?.(handoff)}
597+
/>
598+
))}
584599
<ThreadFeed
585600
key={props.selectedThread.id}
586601
environmentId={props.environmentId}
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import type { ThreadHandoff } from "@t3tools/contracts";
2+
import { Pressable, View } from "react-native";
3+
4+
import { AppText as Text } from "../../components/AppText";
5+
import { presentThreadHandoff } from "./thread-handoff-presentation";
6+
7+
export function ThreadHandoffCard(props: {
8+
readonly handoff: ThreadHandoff;
9+
readonly busy?: boolean;
10+
readonly onOpen: () => void;
11+
readonly onDismiss: () => void;
12+
}) {
13+
const { handoff, busy = false, onOpen, onDismiss } = props;
14+
const presentation = presentThreadHandoff(handoff);
15+
return (
16+
<View
17+
accessibilityLabel={presentation.accessibilityLabel}
18+
className="absolute left-3 right-3 top-2 z-20 rounded-2xl border border-border bg-surface px-3 py-2 shadow-sm"
19+
>
20+
<Text className="mb-2 text-sm text-foreground-muted">
21+
Ready to continue in <Text className="font-t3-bold text-foreground">{handoff.title}</Text>.
22+
</Text>
23+
{presentation.artifactReferences ? (
24+
<Text className="-mt-1 mb-2 text-xs text-foreground-muted" numberOfLines={1}>
25+
{presentation.artifactReferences}
26+
</Text>
27+
) : null}
28+
<View className="flex-row gap-2">
29+
<Pressable
30+
accessibilityLabel={presentation.openLabel}
31+
accessibilityRole="button"
32+
disabled={busy}
33+
onPress={onOpen}
34+
className="flex-1 items-center rounded-xl bg-primary px-3 py-2 disabled:bg-subtle-strong"
35+
>
36+
<Text className="font-t3-bold text-sm text-primary-foreground">
37+
{presentation.openLabel}
38+
</Text>
39+
</Pressable>
40+
<Pressable
41+
accessibilityLabel="Dismiss"
42+
accessibilityRole="button"
43+
disabled={busy}
44+
onPress={onDismiss}
45+
className="items-center rounded-xl bg-subtle px-3 py-2 disabled:opacity-50"
46+
>
47+
<Text className="font-t3-bold text-sm text-foreground-muted">Dismiss</Text>
48+
</Pressable>
49+
</View>
50+
</View>
51+
);
52+
}

‎apps/mobile/src/features/threads/ThreadRouteScreen.tsx‎

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,13 @@ import {
1212
requestOlderThreadTurns,
1313
threadHasOlderTurns,
1414
} from "@t3tools/client-runtime/state/threads";
15+
import { findThreadHandoffs } from "@t3tools/client-runtime/state/thread-handoff";
16+
import {
17+
isAtomCommandInterrupted,
18+
squashAtomCommandFailure,
19+
} from "@t3tools/client-runtime/state/runtime";
1520
import { projectScriptCwd, projectScriptRuntimeEnv } from "@t3tools/shared/projectScripts";
16-
import { Platform, ScrollView, View } from "react-native";
21+
import { Alert, Platform, ScrollView, View } from "react-native";
1722
import { useSafeAreaInsets } from "react-native-safe-area-context";
1823
import { useWorkspaceState } from "../../state/workspace";
1924
import { useEnvironmentQuery } from "../../state/query";
@@ -27,6 +32,7 @@ import {
2732
} from "../../components/AndroidScreenHeader";
2833
import { LoadingScreen } from "../../components/LoadingScreen";
2934
import { scopedThreadKey } from "../../lib/scopedEntities";
35+
import { uuidv4 } from "../../lib/uuid";
3036
import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
3137
import { connectionTone } from "../connection/connectionTone";
3238

@@ -62,6 +68,7 @@ import { useSelectedThreadGitState } from "../../state/use-selected-thread-git-s
6268
import { useSelectedThreadRequests } from "../../state/use-selected-thread-requests";
6369
import { useSelectedThreadWorktree } from "../../state/use-selected-thread-worktree";
6470
import { useThreadComposerState } from "../../state/use-thread-composer-state";
71+
import { seedComposerDraftHandoffPrompt } from "../../state/use-composer-drafts";
6572
import { threadEnvironment } from "../../state/threads";
6673
import { projectThreadContentPresentation } from "./threadContentPresentation";
6774
import {
@@ -214,7 +221,14 @@ function ThreadRouteContent(
214221
const gitActions = useSelectedThreadGitActions();
215222
const requests = useSelectedThreadRequests();
216223
const interruptThreadTurn = useAtomCommand(threadEnvironment.interruptTurn, "thread interrupt");
224+
const acceptThreadHandoff = useAtomCommand(threadEnvironment.acceptHandoff, {
225+
reportFailure: false,
226+
});
227+
const dismissThreadHandoff = useAtomCommand(threadEnvironment.dismissHandoff, {
228+
reportFailure: false,
229+
});
217230
const navigation = useNavigation();
231+
const [handoffActionId, setHandoffActionId] = useState<string | null>(null);
218232
const params = props.route.params;
219233
const environmentIdRaw = firstRouteParam(params.environmentId);
220234
const environmentId = environmentIdRaw ? EnvironmentId.make(environmentIdRaw) : null;
@@ -295,6 +309,15 @@ function ThreadRouteContent(
295309
: null,
296310
[composer.interactionMode, composer.modelSelection, composer.runtimeMode, selectedThread],
297311
);
312+
const availableThreadHandoffs = useMemo(
313+
() =>
314+
selectedThreadDetail
315+
? findThreadHandoffs(selectedThreadDetail).filter(
316+
(handoff) => handoff.state === "available",
317+
)
318+
: [],
319+
[selectedThreadDetail],
320+
);
298321

299322
/* ─── Native header theming ──────────────────────────────────────── */
300323
const usesNativeHeaderGlass = NATIVE_LIQUID_GLASS_SUPPORTED;
@@ -496,6 +519,69 @@ function ThreadRouteContent(
496519
},
497520
});
498521
}, [interruptThreadTurn, selectedThread]);
522+
const handleOpenHandoff = useCallback(
523+
async (handoff: ReturnType<typeof findThreadHandoffs>[number]) => {
524+
if (!selectedThread || handoffActionId !== null) {
525+
return;
526+
}
527+
const targetThreadId = ThreadId.make(uuidv4());
528+
setHandoffActionId(handoff.handoffId);
529+
const result = await acceptThreadHandoff({
530+
environmentId: selectedThread.environmentId,
531+
input: {
532+
threadId: selectedThread.id,
533+
handoffId: handoff.handoffId,
534+
targetThreadId,
535+
},
536+
});
537+
if (result._tag === "Failure") {
538+
if (!isAtomCommandInterrupted(result)) {
539+
const error = squashAtomCommandFailure(result);
540+
Alert.alert(
541+
"Could not open handoff thread",
542+
error instanceof Error ? error.message : "Please try again.",
543+
);
544+
}
545+
setHandoffActionId(null);
546+
return;
547+
}
548+
seedComposerDraftHandoffPrompt(
549+
scopedThreadKey(selectedThread.environmentId, targetThreadId),
550+
handoff.handoffId,
551+
handoff.prompt,
552+
);
553+
navigation.navigate("Thread", {
554+
environmentId: String(selectedThread.environmentId),
555+
threadId: String(targetThreadId),
556+
});
557+
setHandoffActionId(null);
558+
},
559+
[acceptThreadHandoff, handoffActionId, navigation, selectedThread],
560+
);
561+
const handleDismissHandoff = useCallback(
562+
async (handoff: ReturnType<typeof findThreadHandoffs>[number]) => {
563+
if (!selectedThread || handoffActionId !== null) {
564+
return;
565+
}
566+
setHandoffActionId(handoff.handoffId);
567+
const result = await dismissThreadHandoff({
568+
environmentId: selectedThread.environmentId,
569+
input: {
570+
threadId: selectedThread.id,
571+
handoffId: handoff.handoffId,
572+
},
573+
});
574+
if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
575+
const error = squashAtomCommandFailure(result);
576+
Alert.alert(
577+
"Could not dismiss handoff",
578+
error instanceof Error ? error.message : "Please try again.",
579+
);
580+
}
581+
setHandoffActionId(null);
582+
},
583+
[dismissThreadHandoff, handoffActionId, selectedThread],
584+
);
499585

500586
const handleOpenTerminal = useCallback(
501587
(nextTerminalId?: string | null) => {
@@ -808,6 +894,10 @@ function ThreadRouteContent(
808894
onSelectUserInputOption={requests.onSelectUserInputOption}
809895
onChangeUserInputCustomAnswer={requests.onChangeUserInputCustomAnswer}
810896
onSubmitUserInput={requests.onSubmitUserInput}
897+
availableHandoffs={availableThreadHandoffs}
898+
handoffActionId={handoffActionId}
899+
onOpenHandoff={handleOpenHandoff}
900+
onDismissHandoff={handleDismissHandoff}
811901
/>
812902
</View>
813903
</>
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { ThreadHandoffId, ThreadId, TurnId } from "@t3tools/contracts";
2+
import { describe, expect, it } from "vite-plus/test";
3+
4+
import { presentThreadHandoff } from "./thread-handoff-presentation";
5+
6+
describe("presentThreadHandoff", () => {
7+
it("keeps the mobile card focused on open or dismiss while retaining artifact context", () => {
8+
expect(
9+
presentThreadHandoff({
10+
sourceThreadId: ThreadId.make("source"),
11+
handoffId: ThreadHandoffId.make("handoff"),
12+
requestingTurnId: TurnId.make("turn-1"),
13+
title: "Implementation",
14+
prompt: "Implement docs/internals/spec.md",
15+
artifactReferences: ["docs/internals/spec.md"],
16+
state: "available",
17+
targetThreadId: null,
18+
requestedAt: "2026-08-18T12:00:00.000Z",
19+
resolvedAt: "2026-08-18T12:01:00.000Z",
20+
}),
21+
).toEqual({
22+
accessibilityLabel: "Thread handoff: Implementation",
23+
openLabel: "Open Implementation thread",
24+
artifactReferences: "docs/internals/spec.md",
25+
});
26+
});
27+
});
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import type { ThreadHandoff } from "@t3tools/contracts";
2+
3+
export function presentThreadHandoff(handoff: ThreadHandoff) {
4+
return {
5+
accessibilityLabel: `Thread handoff: ${handoff.title}`,
6+
openLabel: `Open ${handoff.title} thread`,
7+
artifactReferences:
8+
handoff.artifactReferences.length > 0 ? handoff.artifactReferences.join(" · ") : null,
9+
};
10+
}

‎apps/mobile/src/state/use-composer-drafts.test.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ import {
1111
mergeComposerDraftContentState,
1212
removeComposerDraftsForEnvironment,
1313
restoreComposerDraftSnapshotState,
14+
seedComposerDraftHandoffPrompt,
15+
setComposerDraftText,
1416
} from "./use-composer-drafts";
1517

1618
const DRAFT: ComposerDraft = {
@@ -23,6 +25,23 @@ afterEach(() => {
2325
});
2426

2527
describe("mobile composer drafts", () => {
28+
it("seeds a handoff target exactly once after the user clears it", () => {
29+
const draftKey = "environment-1:handoff-target";
30+
31+
seedComposerDraftHandoffPrompt(draftKey, "handoff-1", "Implement the prepared work.");
32+
expect(getComposerDraftSnapshot(draftKey)).toMatchObject({
33+
text: "Implement the prepared work.",
34+
seededHandoffIds: ["handoff-1"],
35+
});
36+
37+
setComposerDraftText(draftKey, "");
38+
seedComposerDraftHandoffPrompt(draftKey, "handoff-1", "Do not put this back.");
39+
expect(getComposerDraftSnapshot(draftKey)).toMatchObject({
40+
text: "",
41+
seededHandoffIds: ["handoff-1"],
42+
});
43+
});
44+
2645
it("hydrates selector state even when the message content is empty", () => {
2746
expect(
2847
decodePersistedComposerDrafts({

‎apps/mobile/src/state/use-composer-drafts.ts‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ export interface ComposerDraft {
4545
readonly runtimeMode?: RuntimeMode;
4646
readonly interactionMode?: ProviderInteractionMode;
4747
readonly workspaceSelection?: ComposerDraftWorkspaceSelection;
48+
/** Receipts prevent an intentionally cleared handoff prompt from returning. */
49+
readonly seededHandoffIds?: ReadonlyArray<string>;
4850
}
4951

5052
export interface ComposerDraftContent {
@@ -80,6 +82,7 @@ const ComposerDraftSchema = Schema.Struct({
8082
runtimeMode: Schema.optional(RuntimeModeSchema),
8183
interactionMode: Schema.optional(ProviderInteractionModeSchema),
8284
workspaceSelection: Schema.optional(ComposerDraftWorkspaceSelectionSchema),
85+
seededHandoffIds: Schema.optional(Schema.Array(Schema.String)),
8386
});
8487

8588
const PersistedComposerDraftsSchema = Schema.Struct({
@@ -131,7 +134,8 @@ function isEmptyDraft(draft: ComposerDraft): boolean {
131134
draft.modelSelection === undefined &&
132135
draft.runtimeMode === undefined &&
133136
draft.interactionMode === undefined &&
134-
draft.workspaceSelection === undefined
137+
draft.workspaceSelection === undefined &&
138+
(draft.seededHandoffIds?.length ?? 0) === 0
135139
);
136140
}
137141

@@ -276,6 +280,28 @@ export function setComposerDraftText(draftKey: string, value: string): void {
276280
});
277281
}
278282

283+
export function seedComposerDraftHandoffPrompt(
284+
draftKey: string,
285+
handoffId: string,
286+
prompt: string,
287+
): void {
288+
updateComposerDrafts((current) => {
289+
const existing = normalizeDraft(current[draftKey]);
290+
const seededHandoffIds = existing.seededHandoffIds ?? [];
291+
if (seededHandoffIds.includes(handoffId)) {
292+
return current;
293+
}
294+
return {
295+
...current,
296+
[draftKey]: {
297+
...existing,
298+
text: existing.text.length === 0 ? prompt : existing.text,
299+
seededHandoffIds: [...seededHandoffIds, handoffId],
300+
},
301+
};
302+
});
303+
}
304+
279305
export function appendComposerDraftText(draftKey: string, value: string): void {
280306
updateComposerDrafts((current) => {
281307
const existing = normalizeDraft(current[draftKey]);

0 commit comments

Comments
 (0)