[RFC]: Support reviewable session handoff bundles for local developer agents

[ARCJ137442]

Summary

Add an official TouchAI session handoff flow that lets users export the useful context from a TouchAI conversation into a reviewable bundle for local developer agents such as Claude Code or Codex.

The first version should not directly control external tools. It should generate a concise handoff prompt or Markdown file that the user can review, copy, and paste into another agent.

Motivation

TouchAI is a fast AI contact surface: users can summon it quickly, capture intent, explore a problem, and build enough context to decide what should happen next.

For coding tasks, the next step is often a local developer agent. Today that transition is manual. A user or downstream agent must restate the task, reconstruct conversation history, infer what matters, and sometimes inspect TouchAI's local session database to recover context.

A recent local reverse-engineering exercise showed that this is technically possible but too fragile for normal users: the downstream agent had to locate the correct local database, understand session/message relationships, sort messages safely, distinguish metadata from content, and verify whether long messages were complete or truncated.

That experience points to a clearer product need: TouchAI should provide a stable, official, user-reviewed session handoff bundle so downstream agents do not need to reverse-engineer local storage.

Affected boundaries

• session persistence
• context construction

The initial design should avoid:

• tool execution
• instruction loading
• agent orchestration
• MCP integration
• database schema or migrations

Proposed design

Phase 1: copy/export handoff bundle

Add a user action in the conversation UI, such as "Handoff to developer agent".

When triggered, TouchAI generates a reviewable handoff bundle from the current session.

The bundle should include:

• current user goal
• concise conversation summary
• important user constraints or preferences
• relevant assistant conclusions
• open questions or unverified assumptions
• referenced files or attachment paths when available and safe
• non-sensitive model/provider metadata when useful
• provenance labels that separate user-provided content from assistant-generated interpretation

The bundle should not include:

• API keys or provider secrets
• hidden configuration
• full raw tool outputs by default
• unrelated historical messages
• local absolute paths unless the user confirms them
• external agent configuration changes
• AI-generated claims presented as user-confirmed facts

Supported outputs for the first version:

1. Copy handoff prompt to clipboard
2. Export handoff Markdown to a user-selected location

Example bundle shape:

You are taking over from a TouchAI conversation.

User goal:
...

Current understanding:
...

Important constraints:
...

Relevant context:
...

Unverified assumptions:
...

Suggested next step:
...

Phase 2: local developer-agent affordances

After the bundle format is validated, TouchAI can optionally detect local Claude Code / Codex availability and offer lightweight actions:

• copy the bundle and show a "continue in Claude Code / Codex" hint
• open the project directory in a terminal
• save a handoff Markdown file near the selected workspace
• provide tool-specific command suggestions

This phase should still avoid sending commands into external tools unless a separate design is accepted.

Phase 3: bidirectional handoff

A later design can explore the reverse direction:

• importing a summary from Claude Code / Codex back into TouchAI
• forking a TouchAI session from downstream agent work
• preserving traceability between the original TouchAI session and follow-up implementation work

This should be treated separately because it raises deeper questions around state ownership, privacy, conflict handling, and cross-agent session identity.

Alternatives and trade-offs

Manual copy from the UI

Users can already copy parts of a conversation manually, but this loses structure and often misses constraints, open questions, and provenance.

Downstream agents read TouchAI's local database

This is possible but not appropriate as a product workflow. It depends on internal schema knowledge, local installation paths, SQLite behavior, and careful read-only handling. It also creates unnecessary privacy and safety risk.

Directly launch Claude Code / Codex with full context

This gives the smoothest experience, but it is higher risk. It requires tool detection, process launching, command construction, OS-specific behavior, and stronger guarantees around sensitive context review.

Upstream references

Related issue:

• [Feature]: Import existing Claude Code or Codex API settings during onboarding #431 reduces setup friction by importing Claude Code / Codex API settings.
• This RFC addresses the next step: reducing context-switching friction after a TouchAI session has already produced useful working context.

Testing and rollout

Phase 1 can be validated without external tool automation.

Tests should cover:

• short sessions
• long sessions
• sessions where the title no longer represents the latest topic
• sessions with assistant-generated summaries
• sessions with tool calls or attachments
• masking or omission of sensitive fields
• stable Markdown formatting
• preserving user/assistant provenance

Manual validation should cover:

• copying the bundle into Claude Code
• copying the bundle into Codex
• checking whether the receiving agent can continue without the user restating the conversation
• checking that the exported bundle is concise and reviewable rather than a raw transcript

Rollout can start with "Copy handoff prompt". File export and local tool detection can follow after the bundle shape is accepted.

[hiqiancheng]

Scope update: treat this as the first step of Agent 主理

After further product discussion, I think this RFC should be positioned as the first step of a broader TouchAI capability tentatively called Agent 主理.

The original handoff bundle idea is still valuable, but the product goal is larger than a one-time copy/paste handoff:

• TouchAI should be the place where users clarify an intent and gather useful context.
• TouchAI should then help route that work to an appropriate local developer agent.
• The user should be able to review what is being sent, understand which agent can handle it, and later continue from either the target agent app or TouchAI.
• Over time, TouchAI should be able to keep agent status, task references, progress, user confirmations, and final results in one traceable task thread.

So instead of defining this only as session handoff, I would frame it as:

Agent 主理: TouchAI's general agent-management and task-continuation capability. TouchAI prepares the task context, connects or delegates to a suitable agent, tracks the execution state where possible, and keeps the result tied back to the original TouchAI context.

First supported agents

The first batch should target local developer agents:

• OpenCode
• Claude Code
• Codex
• Gemini CLI

The design should not hard-code Codex as the only downstream target. Codex can be one adapter, but the bundle and settings model should be agent-agnostic.

Proposed split for the first stage

I suggest splitting the first stage into two related pieces.

1. Agent 主理: task brief

This issue can remain focused on generating a reviewable task brief from the current TouchAI session.

The task brief should work as the universal fallback for all agents, including agents that cannot yet be launched or controlled directly by TouchAI.

It should include:

• user goal
• relevant context
• constraints and preferences
• assistant conclusions, clearly marked as assistant interpretation
• open questions and unverified assumptions
• suggested next step
• safe references to files or attachments when available
• machine-readable metadata for source, timestamp, session id, and provenance schema

It should avoid:

• secrets and provider keys
• hidden config
• raw tool output by default
• unrelated history
• local absolute paths unless explicitly confirmed
• presenting assistant-generated claims as user-confirmed facts

Initial output actions:

• copy task brief
• export Markdown

2. Agent 主理: settings center

A separate but closely related first-stage issue should add a new Agent 主理 tab in Settings.

This tab should manage the first batch of supported agents: OpenCode, Claude Code, Codex, and Gemini CLI.

Each agent card should show:

• enabled / disabled switch
• state: current default, available, available with warnings, unavailable, disabled
• detected binary path
• version
• connection mode: CLI, JSON stream, ACP, server, or task-brief-only fallback
• login / credential status, without exposing sensitive values
• capability matrix: start task, stream progress, resume session, cancel task, open native UI, return structured result
• last detection time
• reason / impact / recovery suggestion for the current state
• actions: refresh detection, set as default, manually choose binary path, copy diagnostics

The important product point is that this should not be a simple boolean like agent enabled. Users need to understand:

1. why an agent is or is not usable,
2. what that means for the current workflow,
3. how to recover.

A useful reference pattern here is CodePilot's separation between setup diagnostics and long-term runtime management: setup/onboarding helps users get started, while Settings owns the persistent runtime state and explanation.

Suggested state model

For each agent adapter:

selected   = currently the default agent
available  = ready to use but not default
degraded   = usable with limitations or warnings
blocked    = cannot currently run
disabled   = user turned it off

Every non-trivial state should include:

reason   = why this state was selected
impact   = what the user can or cannot do
recovery = how to fix it, if applicable

Adapter direction

A future implementation can define a common adapter interface, for example:

interface AgentAdapter {
  id: 'opencode' | 'claude-code' | 'codex' | 'gemini';
  detect(): Promise<AgentDetectionResult>;
  getState(): Promise<AgentState>;
  getCapabilities(): AgentCapabilities;
  createTask?(brief: AgentTaskBrief): Promise<AgentTaskRef>;
  streamEvents?(taskRef: AgentTaskRef): AsyncIterable<AgentEvent>;
  resumeTask?(taskRef: AgentTaskRef): Promise<void>;
  cancelTask?(taskRef: AgentTaskRef): Promise<void>;
  openNative?(taskRef: AgentTaskRef): Promise<void>;
}

The first version does not need every adapter to support every method. The common fallback should always be the reviewable task brief.

Phased path

A practical phased path could be:

1. Generate reviewable task briefs from TouchAI sessions.
2. Add the Agent 主理 settings tab with detection, state, version, path, switches, and capability matrix.
3. Allow users to choose a target agent when generating the task brief.
4. Add direct task start for agents that support reliable non-interactive execution.
5. Store external task/session references.
6. Stream progress and final results back into TouchAI where supported.
7. Let users continue with follow-up instructions, confirmations, cancellation, takeover, and acceptance.

Updated boundary for this RFC

For this issue specifically, I would keep the implementation boundary conservative:

• implement the task brief format and copy/export flow
• make the format agent-agnostic
• preserve provenance labels
• leave direct process launch, ACP integration, session persistence changes, and progress streaming to follow-up issues

This keeps the first version shippable while making sure it is not a dead-end copy/paste feature.

[hiqiancheng]

Implementation notes for the first-stage design

Adding a more concrete implementation note so this RFC can map cleanly onto the current desktop codebase.

Existing TouchAI surfaces that fit this feature

Natural places to integrate the first stage:

• Conversation state and message model: apps/desktop/src/types/session.ts
• Session history restore / message loading: apps/desktop/src/services/AgentService/session/history.ts
• Current SearchView state: apps/desktop/src/views/SearchView/index.vue
• Conversation toolbar entry point: apps/desktop/src/views/SearchView/components/ConversationPanel/components/ConversationToolbar.vue
• Clipboard copy path: apps/desktop/src/services/ClipboardService/index.ts
• Export-file pattern: apps/desktop/src/database/backup.ts
• Settings navigation: apps/desktop/src/views/SettingsView/settingsNavigation.ts
• Settings shell: apps/desktop/src/views/SettingsView/index.vue

Suggested Phase 1 frontend shape

Conversation action

Add a conversation toolbar action such as:

• 生成任务说明
• or a menu item under an overflow action if the toolbar should stay compact

Clicking it should open a review surface before copying/exporting. The first version should not silently copy a generated brief without review.

Review surface actions:

• 复制任务说明
• 导出 Markdown
• optional: 选择 Agent if the Agent 主理 settings tab already exists

Task brief module

Create a small, deterministic builder rather than embedding formatting logic in Vue components.

Possible module shape:

interface AgentTaskBriefInput {
  sessionId: string | null;
  messages: SessionMessage[];
  sessionTitle?: string | null;
  createdAt?: number;
}

interface AgentTaskBrief {
  markdown: string;
  metadata: {
    source: 'TouchAI';
    schemaVersion: 1;
    sessionId: string | null;
    generatedAt: string;
  };
  warnings: string[];
}

function buildAgentTaskBrief(input: AgentTaskBriefInput): AgentTaskBrief;

Recommended location:

• apps/desktop/src/services/AgentHandoffService/
• or apps/desktop/src/services/AgentOrchestrationService/brief.ts if the broader Agent 主理 naming is preferred

The builder should be deterministic and testable. It should not call a model in Phase 1. If a model-generated summary is added later, it should be an optional enhancement with a clear provenance label.

Markdown format

Keep the Markdown readable for humans and parseable for future agents.

Suggested top matter:

---
source: TouchAI
kind: agent-task-brief
schema_version: 1
session_id: ...
generated_at: ...
provenance: user_facts | assistant_interpretation | unverified_assumption
---

Suggested sections:

# TouchAI Agent Task Brief

## User Goal

## User-Provided Context

## Assistant Interpretation

## Constraints And Preferences

## Open Questions

## Suggested Next Step

## Source Notes

Important: do not mix trust levels. User-provided facts, assistant interpretations, and unverified assumptions should remain separate.

Agent 主理 settings tab

If the settings tab is implemented in parallel or follow-up, it should be added as a top-level settings navigation item under the AI capability group.

Current file to extend:

• apps/desktop/src/views/SettingsView/settingsNavigation.ts

Suggested section id:

type NavigationSection =
  | 'general'
  | 'ai-services'
  | 'built-in-tools'
  | 'mcp-tools'
  | 'agent-stewardship'
  | 'data-management';

Suggested UI label:

• Chinese: Agent 主理
• English fallback: Agents

The settings view shell would add an async component similar to the existing settings pages:

const AgentStewardshipView = defineAsyncComponent(
  () => import('./components/AgentStewardship/index.vue')
);

The tab should show one card per first-batch agent:

• OpenCode
• Claude Code
• Codex
• Gemini CLI

Each card should expose:

• enable switch
• state pill
• binary path
• version
• connection modes
• login / credential status
• capability matrix
• last checked time
• reason / impact / recovery
• actions: refresh, set default, choose binary, copy diagnostics

Native detection layer

Agent detection should happen in the native/Tauri layer rather than directly in Vue.

Initial commands can stay read-only:

• locate binary by configured path, PATH lookup, and common install locations
• run --version with timeout
• optionally run a lightweight auth/status command when the agent supports it
• return structured status

Do not mutate external agent configuration in this phase.

Suggested result shape:

type AgentRuntimeState = 'selected' | 'available' | 'degraded' | 'blocked' | 'disabled';

type AgentCapability =
  | 'task_brief'
  | 'start_task'
  | 'stream_progress'
  | 'resume_session'
  | 'cancel_task'
  | 'open_native_ui'
  | 'structured_result';

interface AgentDetectionResult {
  id: 'opencode' | 'claude-code' | 'codex' | 'gemini';
  label: string;
  enabled: boolean;
  state: AgentRuntimeState;
  version: string | null;
  binaryPath: string | null;
  connectionModes: string[];
  capabilities: AgentCapability[];
  lastCheckedAt: string;
  reason: string;
  impact: string;
  recovery?: string;
}

Persistence boundary

Phase 1 task brief generation can avoid database migrations.

The settings center likely needs persistence for:

• enabled/disabled per agent
• manually configured binary path
• default agent id
• user preference for review-before-start
• whether TouchAI may keep external session references

This can start as settings key/value entries if that matches the current settings storage pattern, and evolve to a dedicated table only when task/session references are introduced.

Testing notes

Task brief tests:

• short session
• long session
• mixed user/assistant messages
• assistant reasoning/tool parts present
• attachments present
• sensitive-looking values are omitted or warned
• local absolute paths are omitted unless confirmed
• Markdown formatting is stable
• provenance sections remain separated

Agent settings tests:

• no agents installed
• agent installed but disabled
• binary found but version command fails
• manually configured path overrides PATH
• degraded state shows reason/impact/recovery
• default agent cannot be selected when blocked or disabled
• copy diagnostics masks sensitive values

Out of scope for this issue

Still recommend keeping these out of the first implementation:

• directly launching external agents
• ACP or server integration
• progress streaming
• external session reference persistence
• editing external agent config files
• importing external agent memory/instructions
• database schema migrations unless the settings tab requires them

This keeps #433 small enough to ship while aligning it with the Agent 主理 direction.

[hiqiancheng]

First-batch agent adapter matrix

Adding a more concrete adapter matrix for the first supported agents. The main point is that TouchAI should not assume every agent has the same depth of integration. The settings UI should expose capability differences clearly and fall back to the reviewable task brief when a direct integration is missing or risky.

Capability vocabulary

Suggested capability flags:

task_brief          = can receive a generated Markdown/prompt brief manually
start_task          = TouchAI can start a non-interactive task
stream_progress     = TouchAI can parse structured or line-oriented progress
resume_session      = TouchAI can continue a previous external session
cancel_task         = TouchAI can stop a running process/session
open_native_ui      = TouchAI can open the target app/session view
structured_result   = TouchAI can get parseable final result/events
permission_bridge   = TouchAI can surface external tool approvals or permission prompts

Initial adapter expectations

Agent	Detection	Minimum integration	Better integration	Notes
OpenCode	PATH/manual path + opencode --version	task brief fallback	opencode run, opencode serve, opencode acp, JSON/session-aware flows where available	Good candidate for deeper adapter because it exposes CLI, server, session, and ACP-style surfaces.
Claude Code	PATH/manual path + claude --version	task brief fallback	claude -p / print mode, structured output, resume/session flags, permission modes	Strong candidate for direct execution and session continuation. Need to avoid silently editing ~/.claude config.
Codex	PATH/manual path + codex --version	task brief fallback	codex exec --json, sandbox controls, resume where available	Good for non-interactive execution and JSONL event parsing. Need separate validation before claiming tasks appear in Codex App automatically.
Gemini CLI	PATH/manual path + gemini --version	task brief fallback	gemini -p headless prompt, JSON output where available, ACP mode when stable enough	Treat ACP support as experimental/degraded until verified across platforms.

Detection strategy

Each adapter should support three detection layers:

1. user-configured binary path
2. PATH lookup
3. common install locations per OS

Detection should be read-only and time-bounded:

• resolve binary path
• run --version
• optionally run a lightweight status/auth command if the agent supports one
• never write external config during detection
• cache detection results briefly to avoid slow Settings rendering

Suggested per-agent binary names:

opencode:    opencode
claude-code: claude
codex:       codex
gemini:      gemini

State examples

available

Binary exists, version command works, required credentials/login appear valid or are not required for the selected connection mode.

degraded

Examples:

• binary exists but version is unknown
• can generate/copy task brief but cannot start process directly
• direct execution works but progress cannot be streamed structurally
• ACP/server mode exists but is experimental or not verified on this OS
• login status cannot be checked, so the first run may still fail

blocked

Examples:

• binary not found
• manually configured binary path no longer exists
• version command times out
• required login or credentials are missing
• configured connection mode is unavailable

disabled

User explicitly turned this agent off. Disabled agents should not appear as default candidates, but can still keep their saved path/settings.

Suggested settings card fields per agent

Name
Enabled switch
State pill
Version
Binary path
Connection mode
Credential/login status
Capabilities
Last checked
Reason
Impact
Recovery
Actions: refresh, set default, choose binary, copy diagnostics

The copy diagnostics action should mask sensitive values and include only safe fields: agent id, state, version, binary basename/path if user allows path sharing, connection mode, capabilities, last error class, and OS.

Recommended default selection rules

• If the user explicitly sets a default agent, respect it unless disabled or blocked.
• If the default is blocked, show a visible degraded/fallback explanation instead of silently picking another agent.
• If no default is set, choose the first enabled + available agent by user order.
• If no agent is available, offer only 生成任务说明.
• Do not auto-enable newly detected agents without showing them in Settings first.

Launching should be a later phase

For the current RFC, the safest implementation remains:

1. generate task brief,
2. optionally let the user choose a target agent label,
3. copy/export the brief,
4. use Settings to show whether each agent is ready for future direct launch.

Direct start_task should be introduced only after the settings state model is in place, because launching an external developer agent without clear availability, permission, and recovery UX will make failures feel mysterious.

Useful official references to verify during implementation

• OpenCode CLI / server / ACP docs
• Claude Code CLI reference for print mode, structured output, resume/session behavior, and permissions
• Codex CLI non-interactive codex exec --json behavior and sandbox/resume behavior
• Gemini CLI headless prompt / JSON output / ACP mode docs

Implementation should verify the exact command flags against official docs and the installed local version at runtime, because these CLIs are moving targets.