@danceiny/gotry 0.2.0-rc.29 → 0.2.0-rc.31

package/dist/src/index.js

@@ -42,12 +42,15 @@ import { generateItineraryDeckExport } from '../capabilities/itinerary-deck-expo
 import { interpretEffect, declinedObservation } from '../capabilities/effect.js';
 import { customerSendCode, customerLogin } from '../capabilities/hbcli.js';
 import { FLYAI_POI_CATEGORIES } from '../capabilities/flyai.js';
+import { registerGotryWebApi } from './gotry-web-api.js';
+import { registerArtifactDeliveries } from './artifact-delivery.js';
 import { createFlyaiSetupTool } from './flyai-setup-tool.js';
 import { appendFacts, loadFactRegistry } from '../capabilities/fact-log.js';
 import { factsFromFlyai, factsFromHotel, factsFromSession, factsFromSessionTrain } from './bookable-facts.js';
 import { hasRecognizedAvailableSeat } from '../capabilities/session/adapters/rail-12306.js';
 import { gateArtifact } from './artifact-gate.js';
 import { installTurnDeadline, listTurnHandoffTickets } from './turn-deadline.js';
+import { startTurnHandoffJob } from './turn-handoff-job.js';
 import { noteChannelVerdict, recordChannelEvent, readLatestChannelEvents } from '../capabilities/channel-health.js';
 import { routingAdvice, renderRoutingCard, toolRoutingHeadline, persistedDownChannels } from '../capabilities/channel-registry.js';
 import { registerBenchmarkEnvironmentBridge } from './benchmark-environment-bridge.js';
@@ -428,12 +431,20 @@ export function apply(ctx, config, seams = {}) {
     // 固定 policy 保证评测可复现,不走路由。GOTRY_HANDOFF_CHILD=1 是收集器
     // 派生的后台规划会话:唯一出口 converge + 长 leash——前台转后台,后台
     // 必须产出最终交付物,不得再次 handoff(否则无限递归)。
+    if (!rawBenchmarkEnvironmentConfigPath) {
+        registerGotryWebApi(ctx, config.stateRoot ?? '.');
+        registerArtifactDeliveries(ctx);
+    }
     const handoffChild = process.env.GOTRY_HANDOFF_CHILD === '1';
     installTurnDeadline(ctx, handoffChild
         ? { fixedPolicy: { softMs: 300_000, hardMs: 900_000, exit: 'converge' } }
         : rawBenchmarkEnvironmentConfigPath.trim()
             ? { fixedPolicy: benchmarkPinnedPolicy() }
-            : { stateRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.' });
+            : { stateRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.',
+                // A one-shot headless process exits after its final response and cannot
+                // own ongoing work. Keep that ticket queued for explicit collection.
+                startHandoff: (ticket, agent, root) => typeof ctx.get === 'function' && ctx.get('connection')
+                    ? startTurnHandoffJob(ctx, ticket, agent, root) : Promise.resolve(ticket) });
     if (rawBenchmarkEnvironmentConfigPath.trim()) {
         // Benchmark mode is a deliberately minimal kernel: only the model
         // override and the environment bridge are installed besides the pinned
@@ -987,8 +998,8 @@ export function apply(ctx, config, seams = {}) {
     registerGuarded(defineTool({
         name: 'gotry_turn_handoff_list',
         description: 'List background deep-planning handoff tickets (read-only). Call this whenever the user asks about '
-            + 'a previously handed-off plan («规划好了吗» / «上次那个行程»): open = still being worked in the '
-            + 'background (ETA ' + '约 1 小时' + '), settled = deliverable ready (excerpt included, full text in the '
+            + 'a previously handed-off plan («规划好了吗» / «上次那个行程»): open = queued, worker not started; '
+            + 'running = started with a native job id (use job_list for live status); settled = deliverable ready (excerpt included, full text in the '
             + 'ticket\'s .deliverable.md), failed = honest failure note. Never fabricate a deliverable that is not here.',
         // D-30 第三刀(issue #112):query blob → 平铺 typed;全字段可选 → interpretArgs 容忍层(同 session 刀法)
         parameters: {
@@ -998,9 +1009,10 @@ export function apply(ctx, config, seams = {}) {
             schema: { type: 'json' },
             render: (_args, value) => [{ type: 'text', text: String(value.summary ?? '') }],
         },
-        async execute(args, _exec) {
+        async execute(args, exec) {
             const q = interpretArgs(args);
-            const root = process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.';
+            const configuredRoot = process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.';
+            const root = configuredRoot === '.' ? sessionCwd(exec) ?? '.' : configuredRoot;
             const all = await listTurnHandoffTickets(root);
             const tickets = (q.ticketId ? all.filter(t => t.id === q.ticketId) : all).slice(0, 10);
             if (tickets.length === 0) {
@@ -1014,10 +1026,19 @@ export function apply(ctx, config, seams = {}) {
             const lines = tickets.map(t => {
                 const head = `[${t.status}] ${t.id} ${t.objective.slice(0, 40)}`;
                 if (t.status === 'open')
-                    return `${head}——后台规划中,ETA ${t.etaLabel}`;
+                    return `${head}——待启动，后台尚未运行`;
+                if (t.status === 'running') {
+                    const owner = exec.agent;
+                    // Native counters restart with the host. A recycled id alone is not
+                    // the durable ticket's identity and must not offer another trip's job.
+                    const live = owner && ctx.get('jobs')?.list(owner.id).some(job => job.id === t.jobId
+                        && job.owner === owner.id && job.kind === 'gotry-planning' && job.label.startsWith(`${t.id}: `)
+                        && (job.status === 'running' || job.status === 'stopping'));
+                    return `${head}——${live ? `后台任务 ${t.jobId}，预计 ${t.etaLabel}` : '运行记录已中断，当前没有活跃后台任务'} `;
+                }
                 if (t.status === 'failed')
                     return `${head}——失败:${t.error ?? '未知原因'}(请重新发起规划)`;
-                return `${head}——已交付,摘要:${(t.deliverableExcerpt ?? '').slice(0, 120).replace(/\n/g, ' ')}`;
+                return `${head}——${t.deliverablePath ? `已交付：${t.deliverablePath}` : '交付文件缺失'}，摘要:${(t.deliverableExcerpt ?? '').slice(0, 120).replace(/\n/g, ' ')}`;
             });
             return {
                 ok: true, count: tickets.length, tickets,
@@ -2355,6 +2376,7 @@ export function apply(ctx, config, seams = {}) {
             try {
                 r = await listArtifacts({
                     stateRoot: config.stateRoot ?? '.',
+                    handoffRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? ((config.stateRoot ?? '.') === '.' ? sessionCwd(exec) ?? '.' : config.stateRoot),
                     cwd: sessionCwd(exec),
                     limit: q.limit,
                     offset: q.offset,
@@ -2448,7 +2470,7 @@ export function apply(ctx, config, seams = {}) {
                 throw new Error('gotry_artifacts_read requires path');
             if (!q.path)
                 return JSON.parse(JSON.stringify({ ok: false, error: 'path 必填(来自 gotry_artifacts_list)' }));
-            const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', cwd: sessionCwd(exec), path: q.path, offset: q.offset, limit: q.limit });
+            const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', handoffRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? ((config.stateRoot ?? '.') === '.' ? sessionCwd(exec) ?? '.' : config.stateRoot), cwd: sessionCwd(exec), path: q.path, offset: q.offset, limit: q.limit });
             if (!r.ok)
                 return JSON.parse(JSON.stringify(r));
             // 身份/来源展示(issue #285 第 1 条「显示身份/来源」):行号视图保留 read 卡的

package/dist/src/turn-deadline.js

@@ -13,18 +13,47 @@
  *   `gotry_turn_handoff.v1` 工单并指令模型告知用户 ETA 与回访方式。
  * - handoff 工单是**新的独立格式**,落在 `<stateRoot>/gotry-state/
  *   turn-handoffs/`,不与 `async/` 的 loop 求解工单混用——async-collect
- *   对无 spec 的 state 会立即结算 failed(假失败),收集器是未来的
- *   agent tick(loopx),不是 async-collect。
+ *   对无 spec 的 state 会立即结算 failed(假失败)。产品通过原生 jobs
+ *   启动独立收集器;仅落单不代表后台已开始。
  */
 import { randomUUID } from 'node:crypto';
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { classifyTurn, TURN_HANDOFF_ETA_LABEL, turnPolicyFor } from './turn-policy.js';
 export const TURN_DEADLINE_SOFT = 'TURN_DEADLINE_SOFT';
 export const TURN_DEADLINE_EXHAUSTED = 'TURN_DEADLINE_EXHAUSTED';
 export const TURN_DEADLINE_HANDOFF = 'TURN_DEADLINE_HANDOFF';
 export const TURN_HANDOFF_SCHEMA = 'gotry_turn_handoff.v1';
-export async function writeTurnHandoffTicket(stateRoot, userMessage) {
+function handoffContext(events) {
+    const questionIds = new Set(events.filter(event => event.type === 'tool/call' && event.data.name === 'ask_user_question')
+        .map(event => event.type === 'tool/call' ? event.data.callId : ''));
+    // Human constraints are lossless. Refuse dispatch if they exceed the input
+    // budget; silently cutting an accessibility/budget answer changes the task.
+    const answers = events.filter(event => (event.type === 'user/message' && event.data.source.kind === 'user')
+        || (event.type === 'tool/call' && questionIds.has(event.data.callId))
+        || (event.type === 'tool/result' && event.data.message.source.kind === 'tool' && questionIds.has(event.data.message.source.callId)))
+        .map(event => JSON.stringify(event.data)).join('\n');
+    if (answers.length > 64_000)
+        throw new Error('Prior user answers exceed the handoff context limit; planning paused without dropping constraints. Start a new session with the complete trip constraints.');
+    let remaining = 18_000;
+    const evidence = [];
+    for (const event of [...events].reverse()) {
+        if (event.type !== 'tool/result' || (event.data.message.source.kind === 'tool' && questionIds.has(event.data.message.source.callId)))
+            continue;
+        const row = JSON.stringify(event.data);
+        // Evidence may be excerpted, with an explicit marker and valid JSON.
+        const excerpt = row.length > remaining
+            ? JSON.stringify({ truncated: true, excerpt: row.slice(-Math.floor(remaining / 2)) }) : row;
+        if (excerpt.length + 1 > remaining)
+            break;
+        evidence.unshift(excerpt);
+        remaining -= excerpt.length + 1;
+        if (remaining < 100)
+            break;
+    }
+    return answers || evidence.length ? `${answers}\n${evidence.join('\n')}` : undefined;
+}
+export async function writeTurnHandoffTicket(stateRoot, userMessage, details = {}) {
     const ticket = {
         schema: TURN_HANDOFF_SCHEMA,
         id: `th-${Date.now().toString(36)}-${randomUUID().slice(0, 6)}`,
@@ -33,6 +62,7 @@ export async function writeTurnHandoffTicket(stateRoot, userMessage) {
         requestedAt: new Date().toISOString(),
         etaLabel: TURN_HANDOFF_ETA_LABEL,
         status: 'open',
+        ...details,
     };
     await writeTicketJson(stateRoot, ticket);
     return ticket;
@@ -41,7 +71,7 @@ function handoffDir(stateRoot) {
     const root = stateRoot === '.' ? process.cwd() : stateRoot;
     return join(root, 'gotry-state', 'turn-handoffs');
 }
-async function writeTicketJson(stateRoot, ticket) {
+export async function writeTicketJson(stateRoot, ticket) {
     const dir = handoffDir(stateRoot);
     await mkdir(dir, { recursive: true });
     const path = join(dir, `${ticket.id}.json`);
@@ -95,12 +125,14 @@ export async function listTurnHandoffTickets(stateRoot) {
                 objective: raw.objective,
                 requestedAt: raw.requestedAt,
                 etaLabel: raw.etaLabel,
+                ...(raw.jobId ? { jobId: raw.jobId } : {}),
                 ...(raw.settledAt ? { settledAt: raw.settledAt } : {}),
                 ...(raw.error ? { error: raw.error } : {}),
             };
-            if (raw.status !== 'open' && raw.deliverableFile) {
+            if ((raw.status === 'settled' || raw.status === 'failed') && raw.deliverableFile === `${raw.id}.deliverable.md`) {
                 try {
                     const text = await readFile(join(dir, raw.deliverableFile), 'utf-8');
+                    view.deliverablePath = resolve(dir, raw.deliverableFile);
                     view.deliverableExcerpt = text.length > 600 ? `${text.slice(0, 600)}…` : text;
                 }
                 catch { /* 交付物缺失时视图降级,不阻塞列表 */ }
@@ -140,7 +172,12 @@ function exhaustionResult(reason) {
     };
 }
 function handoffResult(ticket) {
-    const instruction = `Turn handed off to background planning. Async ticket ${ticket.id} created (ETA ${ticket.etaLabel}). Stop dispatching tools and tell the user in one short message: the deep planning continues in the background, the expected time, and to check back later (mention ticket ${ticket.id}).`;
+    const state = ticket.status === 'running' && ticket.jobId
+        ? `Background planning started as native background job ${ticket.jobId} (estimated ${ticket.etaLabel}; not a guarantee). Track or cancel with job_list/job_output/job_kill.`
+        : ticket.status === 'failed'
+            ? `Background planning could not start: ${ticket.error ?? 'unknown failure'}. Tell the user it failed; do not promise later delivery.`
+            : 'The ticket is queued; the background worker has not started. Tell the user it is pending, not running; do not promise a completion time.';
+    const instruction = `Async ticket ${ticket.id} persisted. ${state} Stop research and answer from existing results. Never claim a file was created when its tool call failed or was refused. For any successfully written output, call present with its exact existing path before the final response. Mention ticket ${ticket.id}.`;
     return {
         isError: true,
         error: {
@@ -177,6 +214,7 @@ export function installTurnDeadline(ctx, options = {}) {
     };
     const stateByAgent = new Map();
     const softExecutions = new Map();
+    const handoffExecutions = new Map();
     const finalOnlyDisposers = new Map();
     const clearAgent = (agentId) => {
         stateByAgent.delete(agentId);
@@ -184,6 +222,10 @@ export function installTurnDeadline(ctx, options = {}) {
             if (owner.agentId === agentId)
                 softExecutions.delete(token);
         }
+        for (const [token, owner] of handoffExecutions) {
+            if (owner.agentId === agentId)
+                handoffExecutions.delete(token);
+        }
         finalOnlyDisposers.get(agentId)?.();
         finalOnlyDisposers.delete(agentId);
     };
@@ -200,7 +242,7 @@ export function installTurnDeadline(ctx, options = {}) {
         }
         const inheritedNames = globalTools.schemas()
             .map(schema => schema.name)
-            .filter(name => name !== 'run_code');
+            .filter(name => name !== 'run_code' && name !== 'present');
         if (inheritedNames.length === 0)
             return;
         finalOnlyDisposers.set(agentId, scopedTools.restrict({ deny: inheritedNames }));
@@ -249,16 +291,68 @@ export function installTurnDeadline(ctx, options = {}) {
         const state = stateByAgent.get(agentId)
             ?? { startedAt: now(), policy: { ...defaultPolicy, softMs: softPin ?? defaultPolicy.softMs, hardMs: hardPin ?? defaultPolicy.hardMs } };
         stateByAgent.set(agentId, state);
+        // Present validates files on disk and publishes native deliverable events;
+        // it must remain callable after the research window closes.
+        if (exec.name === 'present')
+            return next();
         const elapsed = now() - state.startedAt;
         if (elapsed > state.policy.hardMs) {
-            // Synchronous schema suppression so same-step follow-up calls cannot
-            // loop on refusal results (the 2026-09-02 trajectory failure).
-            enterFinalOnly(exec.agent);
             if (state.policy.exit === 'handoff' && state.userMessage && options.stateRoot) {
-                return writeTurnHandoffTicket(options.stateRoot, state.userMessage)
-                    .then(ticket => handoffResult(ticket))
+                const root = options.stateRoot === '.'
+                    ? (exec.agent.session?.header.cwd ?? process.cwd()) : resolve(options.stateRoot);
+                const written = exec.name === 'write' && !state.handoff ? Promise.resolve().then(() => next()) : undefined;
+                if (!state.handoff) {
+                    const session = exec.agent.session;
+                    // Reserve the handoff before executing the write body. Parallel or
+                    // repeated calls see the same promise and cannot write/dispatch twice.
+                    state.handoff = (async () => {
+                        try {
+                            await written;
+                        }
+                        finally {
+                            enterFinalOnly(exec.agent);
+                        }
+                        let context;
+                        let contextError;
+                        try {
+                            context = handoffContext(session?.snapshotEvents() ?? []);
+                        }
+                        catch (error) {
+                            contextError = error instanceof Error ? error.message : 'handoff context unavailable';
+                        }
+                        const ticket = await writeTurnHandoffTicket(root, state.userMessage, {
+                            workspaceCwd: session?.header.cwd,
+                            ownerSessionId: session ? String(session.id) : undefined,
+                            context,
+                        });
+                        if (contextError) {
+                            await settleTurnHandoffTicket(root, ticket, 'failed', `# Planning paused\n\n${contextError}`, contextError);
+                            return { ...ticket, status: 'failed', error: contextError };
+                        }
+                        return options.startHandoff ? options.startHandoff(ticket, exec.agent, root) : ticket;
+                    })();
+                }
+                // The triggering call may be the output write itself. Execute it once,
+                // preserve its actual outcome, then require native present. Attach a
+                // rejection handler now even if the pending tool itself rejects.
+                const handoff = state.handoff.then(handoffResult, () => exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: ticket persistence failed; no background worker was started`));
+                return (async () => {
+                    const output = await written;
+                    const guidance = await handoff;
+                    if (output) {
+                        handoffExecutions.set(exec.token, { agentId, contexts: guidance.additionalContexts ?? [] });
+                        // Keep the registry's canonical result object. Rebuilding it after
+                        // restricting inherited schemas would make DSH re-resolve a tool
+                        // that has just been hidden and report UNKNOWN_TOOL after saving.
+                        return output;
+                    }
+                    return guidance;
+                })()
                     .catch(() => exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: hard deadline ${state.policy.hardMs}ms reached (ticket persistence failed; degraded to converge)`));
             }
+            // Suppress inherited research schemas immediately on refusal; DSH's
+            // scoped schemas remain visible but hit this same per-call guard.
+            enterFinalOnly(exec.agent);
             return Promise.resolve(exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: turn exceeded hard deadline of ${state.policy.hardMs}ms (elapsed ${elapsed}ms); provide a final answer using existing results`));
         }
         if (elapsed > state.policy.softMs) {
@@ -269,17 +363,20 @@ export function installTurnDeadline(ctx, options = {}) {
     ctx.on('tools/post-execute', (exec, _result, next) => {
         return next().then(decision => {
             const owner = softExecutions.get(exec.token);
-            if (!owner)
+            const handoff = handoffExecutions.get(exec.token);
+            handoffExecutions.delete(exec.token);
+            if (!owner && !handoff)
                 return decision;
             softExecutions.delete(exec.token);
-            const text = owner.exit === 'handoff'
+            const text = owner?.exit === 'handoff'
                 ? 'Turn has crossed the soft deadline of a deep-planning turn. Wrap up context gathering now; the turn will hand off to background planning at the hard deadline.'
                 : 'Turn has crossed the soft deadline. Stop dispatching new tools and produce the final answer from gathered evidence.';
             return {
                 ...decision,
                 additionalContexts: [
                     ...(decision.additionalContexts ?? []),
-                    convergenceContext(TURN_DEADLINE_SOFT, text),
+                    ...(handoff?.contexts ?? []),
+                    ...(owner ? [convergenceContext(TURN_DEADLINE_SOFT, text)] : []),
                 ],
             };
         });

package/dist/src/turn-handoff-job.js

@@ -0,0 +1,124 @@
+/** Connect durable planning tickets to DSH's owned jobs and managed processes. */
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { settleTurnHandoffTicket, writeTicketJson } from './turn-deadline.js';
+const require = createRequire(import.meta.url);
+export async function startTurnHandoffJob(ctx, ticket, owner, stateRoot) {
+    if (ticket.status !== 'open')
+        return ticket;
+    const jobs = ctx.get('jobs');
+    const subprocess = ctx.get('subprocess');
+    if (!jobs || !subprocess)
+        return ticket; // Queued, never announced as running.
+    let current = ticket;
+    let handle;
+    let cancelled = false;
+    let release;
+    const prepared = new Promise(resolve => { release = resolve; });
+    let announceStarted;
+    const started = new Promise(resolve => { announceStarted = resolve; });
+    const fail = async (reason) => {
+        await settleTurnHandoffTicket(stateRoot, current, 'failed', `# Planning failed\n\n${reason}\n\nNo completed plan was produced.`, reason);
+        current = { ...current, status: 'failed', error: reason };
+    };
+    try {
+        const jobId = jobs.start({
+            kind: 'gotry-planning', owner: owner.id, label: `${ticket.id}: ${ticket.objective.slice(0, 100)}`, outputLimitBytes: 12_000,
+            run() {
+                return {
+                    cancel() { cancelled = true; handle?.terminate(); },
+                    done: (async () => {
+                        if (!await prepared) {
+                            announceStarted();
+                            return { status: 'failed', detail: 'ticket persistence failed' };
+                        }
+                        let timer;
+                        try {
+                            if (cancelled)
+                                throw new Error('planning cancelled');
+                            const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+                            const collector = join(import.meta.dirname, '..', 'scripts', `turn-handoff-collect.${extension}`);
+                            const argv = extension === 'ts'
+                                ? [process.execPath, require.resolve('tsx/cli'), collector, ticket.id, stateRoot]
+                                : [process.execPath, collector, ticket.id, stateRoot];
+                            handle = subprocess.spawn({
+                                argv, cwd: ticket.workspaceCwd ?? stateRoot,
+                                stdio: { stdin: 'ignore', stdout: { maxBytes: 16_000 }, stderr: { maxBytes: 16_000 } },
+                                // Collector cleanup includes the wrapper's detached DSH group
+                                // (5s+1s), then its own 8s+1s bound and durable settlement.
+                                graceMs: 11_000,
+                                // This dedicated planning child inherits the configured model
+                                // environment explicitly; secrets never enter tickets or output.
+                                env: { GOTRY_HANDOFF_JOB_ID: current.jobId,
+                                    GOTRY_HANDOFF_PLANNER_BIN: process.env.GOTRY_HANDOFF_PLANNER_BIN,
+                                    GOTRY_HANDOFF_PLANNER_TIMEOUT_MS: process.env.GOTRY_HANDOFF_PLANNER_TIMEOUT_MS,
+                                    DSH_HOME: process.env.DSH_HOME,
+                                    LLM_API_KEY: process.env.LLM_API_KEY, LLM_BASE_URL: process.env.LLM_BASE_URL,
+                                    LLM_MODEL: process.env.LLM_MODEL, GOTRY_LLM_MODEL: process.env.GOTRY_LLM_MODEL,
+                                    DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL },
+                            });
+                            announceStarted();
+                            const plannerTimeout = Number(process.env.GOTRY_HANDOFF_PLANNER_TIMEOUT_MS);
+                            const timeout = Number.isSafeInteger(plannerTimeout) && plannerTimeout > 0 ? plannerTimeout : 900_000;
+                            timer = setTimeout(() => handle.terminate(), timeout + 12_000);
+                            const direct = await handle.done.then(outcome => ({ ok: true, outcome }), error => ({ ok: false, error }));
+                            // Direct success or failure does not prove managed-range exit.
+                            if (!direct.ok)
+                                handle.terminate();
+                            try {
+                                await handle.waitForExit();
+                            }
+                            catch (cleanupError) {
+                                handle.terminate();
+                                const cleanupDiagnostic = cleanupError instanceof Error ? cleanupError.message : 'unknown cleanup error';
+                                const cleanupReason = `managed-range cleanup could not be confirmed: ${cleanupDiagnostic}`;
+                                if (!direct.ok) {
+                                    const diagnostic = direct.error instanceof Error ? direct.error.message : 'planning failed';
+                                    throw new AggregateError([direct.error, cleanupError], `${diagnostic}; ${cleanupReason}`);
+                                }
+                                throw new Error(cleanupReason, { cause: cleanupError });
+                            }
+                            if (!direct.ok)
+                                throw direct.error;
+                            const outcome = direct.outcome;
+                            const path = join(stateRoot, 'gotry-state', 'turn-handoffs', `${ticket.id}.json`);
+                            const settled = JSON.parse(await readFile(path, 'utf8'));
+                            if (cancelled)
+                                throw new Error('planning cancelled');
+                            if (outcome.exitCode !== 0 || settled.status !== 'settled' || settled.deliverableFile !== `${ticket.id}.deliverable.md`) {
+                                throw new Error(settled.error ?? `planning collector failed (exit ${outcome.exitCode ?? outcome.signal})`);
+                            }
+                            const deliverablePath = join(stateRoot, 'gotry-state', 'turn-handoffs', settled.deliverableFile);
+                            const content = await readFile(deliverablePath, 'utf8');
+                            if (!content.trim())
+                                throw new Error('planning collector produced an empty deliverable');
+                            current = settled;
+                            return { status: 'completed', detail: `ticket ${ticket.id} settled`, result: `Planning completed: ${ticket.id}. Deliverable: ${deliverablePath}\nCall present with this exact path, then report the result.\n\n${content.slice(0, 8_000)}` };
+                        }
+                        catch (error) {
+                            const reason = error instanceof Error ? error.message : 'planning failed';
+                            await fail(reason);
+                            return { status: cancelled ? 'killed' : 'failed', detail: reason, result: `Ticket ${ticket.id} failed: ${reason}` };
+                        }
+                        finally {
+                            if (timer)
+                                clearTimeout(timer);
+                            announceStarted();
+                        }
+                    })(),
+                };
+            },
+        });
+        current = { ...ticket, status: 'running', jobId };
+        await writeTicketJson(stateRoot, current);
+        release(true);
+        await started;
+        return current;
+    }
+    catch (error) {
+        release(false);
+        await fail(error instanceof Error ? error.message : 'background job registration failed');
+        return current;
+    }
+}

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Stai Travel Bridge",
-  "version": "0.2.0.29",
+  "version": "0.2.0.31",
   "description": "Stai 连接获准的旅行检索与供应商门户：检索结果经本机或授权后端桥接；门户可触发一次性登录代填，扩展不持久保存凭据。",
   "key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnuzBX8rT8+RZKEUip5VRA0cY056pExy9PNdN9YCiuY3dgglRbcIBhjuFJoR6EX3/MaUv82vJVyItRVrowXLTwDk4WZof0vwFgKL0zBK304PC46pUaAKTSu1PgXeL1+j5KTAGz/9a9+RnPdbj7jND5rM/MOmBHNPVPpp1NlwxRGIgF9OxHSOfXORcH4Iyte1aJSFUJbFtNS/DaE5D+KjyupPLyIqVN/dCiKnNsTCEHQB9ngeli665PFp76hkccHQQZ4sVuMLS4zBPcazUsp1kcnW+xsQoUATkODTCY+Pzk3zUVF1QOESTjRCVnbNi8tkO43RMRs2q63gX/3inFivcEwIDAQAB",
   "permissions": [
@@ -56,5 +56,5 @@
       "run_at": "document_start"
     }
   ],
-  "version_name": "0.2.0-rc.29"
+  "version_name": "0.2.0-rc.31"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danceiny/gotry",
-  "version": "0.2.0-rc.29",
+  "version": "0.2.0-rc.31",
   "description": "GoTry — 从出发到下一次出发的 AI 旅行 Agent(dsh 插件)。npm/源码入口共用锁定的 dsh runtime + README 安装路径。",
   "type": "module",
   "main": "ts/src/index.ts",
@@ -44,7 +44,10 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-tool"
+        "@deepseek-ai/dsh-client-ui-tool",
+        "@deepseek-ai/dsh-client-ui-primitives",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
       ]
     }
   },
@@ -57,6 +60,8 @@
     "bin/",
     "ts/src/index.ts",
     "ts/src/flyai-setup-tool.ts",
+    "ts/src/gotry-web-api.ts",
+    "ts/src/artifact-delivery.ts",
     "ts/src/subagent-job-id-guard.ts",
     "ts/src/benchmark-environment-bridge.ts",
     "ts/src/benchmark-tool-isolation.ts",
@@ -78,6 +83,7 @@
     "ts/src/artifact-gate.ts",
     "ts/src/tool-packet.ts",
     "ts/src/turn-deadline.ts",
+    "ts/src/turn-handoff-job.ts",
     "ts/src/turn-policy.ts",
     "ts/src/memory-capture.ts",
     "ts/src/memory-utility.ts",

package/ts/capabilities/artifacts.ts

@@ -31,7 +31,7 @@ import { isAbsolute, join, resolve, sep } from 'node:path'
 import { openLedgerIfExists } from '../src/state-ledger.ts'
 
 export interface ArtifactEntry {
-  source: 'async-run' | 'cwd-file'
+  source: 'async-run' | 'cwd-file' | 'turn-handoff'
   id: string
   title: string
   path: string
@@ -56,6 +56,8 @@ export interface ArtifactReadView {
 
 export interface ListArtifactsOptions {
   stateRoot: string
+  /** Host-owned handoff storage can differ from the existing async state. */
+  handoffRoot?: string
   cwd?: string
   limit?: number
   /** Zero-based nonnegative integer; values outside the eligible set return an empty page with the known total. */
@@ -266,6 +268,28 @@ async function listCwdArtifacts(cwd: string): Promise<ArtifactEntry[]> {
   return entries
 }
 
+/** Durable handoff outputs live outside async/, including honest failure notes. */
+async function listHandoffArtifacts(root: string): Promise<ArtifactEntry[]> {
+  const dir = join(root, 'gotry-state', 'turn-handoffs')
+  const names = await readdir(dir).catch(() => [] as string[])
+  const entries: ArtifactEntry[] = []
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+    try {
+      const ticket = JSON.parse(await readFile(join(dir, name), 'utf8'))
+      if (ticket.schema !== 'gotry_turn_handoff.v1' || name !== `${ticket.id}.json`
+        || !['settled', 'failed'].includes(ticket.status) || ticket.deliverableFile !== `${ticket.id}.deliverable.md`) continue
+      const path = await realpath(join(dir, ticket.deliverableFile))
+      if (!underRoot(path, root) || hasDeniedSegment(path)) continue
+      const info = await stat(path)
+      if (!info.isFile()) continue
+      entries.push({ source: 'turn-handoff', id: ticket.id, title: String(ticket.objective ?? ticket.id),
+        path, status: ticket.status, updated: new Date(info.mtimeMs).toISOString(), bytes: info.size })
+    } catch { /* A corrupt or missing output cannot be advertised as a file. */ }
+  }
+  return entries
+}
+
 export async function listArtifacts(opts: ListArtifactsOptions): Promise<ListArtifactsResult> {
   const limit = clampLimit(opts.limit)
   const offset = normalizeOffset(opts.offset, 'offset')
@@ -274,6 +298,8 @@ export async function listArtifacts(opts: ListArtifactsOptions): Promise<ListArt
   const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd()
   const canonicalRoot = await realpath(root).catch(() => root)
   const canonicalCwd = await realpath(cwd).catch(() => cwd)
+  const handoffRoot = rootOf(opts.handoffRoot ?? opts.cwd ?? opts.stateRoot)
+  const canonicalHandoffRoot = await realpath(handoffRoot).catch(() => handoffRoot)
 
   // 1) collect all eligible entries per source, without per-source limits —
   //    pageSize is applied to the merged/deduped/sorted set so older cwd files
@@ -281,6 +307,8 @@ export async function listArtifacts(opts: ListArtifactsOptions): Promise<ListArt
   const collected: ArtifactEntry[] = [
     ...listRunsFromLedger(canonicalRoot, 'local'),
     ...(await listDeliverableFiles(canonicalRoot)),
+    ...(await listHandoffArtifacts(canonicalRoot)),
+    ...(canonicalHandoffRoot !== canonicalRoot ? await listHandoffArtifacts(canonicalHandoffRoot) : []),
     ...(await listCwdArtifacts(canonicalCwd)),
   ]
 
@@ -318,6 +346,7 @@ export async function listArtifacts(opts: ListArtifactsOptions): Promise<ListArt
     offset,
     roots: [canonicalRoot, canonicalCwd],
   }
+  if (!result.roots.includes(canonicalHandoffRoot)) result.roots.push(canonicalHandoffRoot)
   if (hasMore) result.nextOffset = start + page.length
   if (needle !== '') result.search = needle
   return result
@@ -332,6 +361,7 @@ export async function listArtifacts(opts: ListArtifactsOptions): Promise<ListArt
  */
 export async function readArtifact(opts: {
   stateRoot: string
+  handoffRoot?: string
   cwd?: string
   path: string
   offset?: number
@@ -341,6 +371,8 @@ export async function readArtifact(opts: {
   const cwd = opts.cwd ? resolve(opts.cwd) : process.cwd()
   const canonicalRoot = await realpath(root).catch(() => root)
   const canonicalCwd = await realpath(cwd).catch(() => cwd)
+  const handoffRoot = rootOf(opts.handoffRoot ?? opts.cwd ?? opts.stateRoot)
+  const canonicalHandoffRoot = await realpath(handoffRoot).catch(() => handoffRoot)
   const raw = String(opts.path ?? '').trim()
   if (!raw) return { ok: false, error: 'path 必填(来自 gotry_artifacts_list 的 path,或异步工单 id)' }
 
@@ -357,10 +389,13 @@ export async function readArtifact(opts: {
       text = run.deliverable
       filePath = asyncDeliverablePath(root, raw)
     } else {
-      const p = asyncDeliverablePath(root, raw)
+      const handoff = /^th-[a-z0-9-]+$/i.test(raw)
+        ? [join(handoffRoot, 'gotry-state', 'turn-handoffs', `${raw}.deliverable.md`),
+          join(root, 'gotry-state', 'turn-handoffs', `${raw}.deliverable.md`)] : []
+      const p = handoff.find(path => existsSync(path)) ?? asyncDeliverablePath(root, raw)
       const canonical = await realpath(p).catch(() => null)
       if (canonical) {
-        if (!underRoot(canonical, canonicalRoot) || hasDeniedSegment(canonical)) {
+        if (!(underRoot(canonical, canonicalRoot) || underRoot(canonical, canonicalHandoffRoot)) || hasDeniedSegment(canonical)) {
           return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` }
         }
         const ext = canonical.slice(canonical.lastIndexOf('.') + 1).toLowerCase()
@@ -384,7 +419,7 @@ export async function readArtifact(opts: {
     // 路径(realpath 后的 cwd),而 macOS 上 /var 与 /private/var 这类符号链接会让
     // canonical 路径不匹配字面 cwd,导致 list→read 串联断裂。边界权威仍是下方
     // realpath 后的 canonical 复检,这里放宽不改变可读集合。
-    const inScope = (p: string) => (underRoot(p, cwd) || underRoot(p, root) || underRoot(p, canonicalCwd) || underRoot(p, canonicalRoot)) && !hasDeniedSegment(p)
+    const inScope = (p: string) => (underRoot(p, cwd) || underRoot(p, root) || underRoot(p, canonicalCwd) || underRoot(p, canonicalRoot) || underRoot(p, handoffRoot) || underRoot(p, canonicalHandoffRoot)) && !hasDeniedSegment(p)
     // Prefer an existing candidate so a cwd miss does not mask a valid state-root file.
     const allowed = candidates.find(p => inScope(p) && existsSync(p)) ?? candidates.find(inScope)
     if (!allowed) {
@@ -394,7 +429,7 @@ export async function readArtifact(opts: {
     if (!canonical) {
       return { ok: false, error: `文件不存在:${raw}`, hint: '先 gotry_artifacts_list 看在册产物' }
     }
-    if (!(underRoot(canonical, canonicalCwd) || underRoot(canonical, canonicalRoot)) || hasDeniedSegment(canonical)) {
+    if (!(underRoot(canonical, canonicalCwd) || underRoot(canonical, canonicalRoot) || underRoot(canonical, canonicalHandoffRoot)) || hasDeniedSegment(canonical)) {
       return { ok: false, error: `路径越界:${raw}`, hint: `只读 ${root} 与 dsh 工作目录内的文本产物` }
     }
     const ext = canonical.slice(canonical.lastIndexOf('.') + 1).toLowerCase()