diff --git a/.github/workflows/ticktick-live-smoke.yml b/.github/workflows/ticktick-live-smoke.yml
new file mode 100644
index 00000000..19707e93
--- /dev/null
+++ b/.github/workflows/ticktick-live-smoke.yml
@@ -0,0 +1,51 @@
+name: ticktick-live-smoke
+
+# The plan's credentialed LIVE contract validation (docs/plans/
+# external-task-views-plan.md): deterministic tests use hand-authored wire
+# values, so upstream TickTick schema/tool drift stays green locally — this job
+# is the drift detector. Scheduled weekly + manually dispatchable; deliberately
+# NOT part of the PR gate (needs a repo secret; must not hammer the live API).
+#
+# Two lanes, each through its production surface (review R10 #3):
+# - OpenAPI (Web lane): the `#[ignore]`d Rust test `live_openapi_contract_smoke`
+# runs the REAL decoder (reqwest → wire.rs → normalize) and asserts
+# representative-shape counters (the smoke account stages due/tags/checklist).
+# - MCP (Worker lane): scripts/ticktick-live-smoke.mjs asserts initialize +
+# tools/list still offer the exact read allowlist.
+# Both are non-capturing: counts/booleans only reach the log.
+
+on:
+ schedule:
+ - cron: "17 6 * * 1"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ smoke:
+ name: live-contract-smoke
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ persist-credentials: false
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: Swatinem/rust-cache@v2
+ with:
+ workspaces: "."
+ shared-key: core
+ - name: Smoke the OpenAPI lane through the production decoder
+ env:
+ TICKTICK_ACCESS_TOKEN: ${{ secrets.TICKTICK_ACCESS_TOKEN }}
+ run: >
+ cargo test --manifest-path crates/core/Cargo.toml
+ live_openapi_contract_smoke -- --ignored --nocapture
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ - name: Smoke the MCP lane (initialize + tools/list allowlist)
+ env:
+ TICKTICK_ACCESS_TOKEN: ${{ secrets.TICKTICK_ACCESS_TOKEN }}
+ run: node scripts/ticktick-live-smoke.mjs
diff --git a/Cargo.lock b/Cargo.lock
index 2e1c5715..fe1bb4c6 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -186,6 +186,7 @@ dependencies = [
"axum",
"base64",
"futures-util",
+ "libc",
"reqwest",
"rust-embed",
"schemars",
@@ -203,6 +204,7 @@ dependencies = [
"tracing",
"tracing-appender",
"tracing-subscriber",
+ "url",
"uuid",
]
diff --git a/apps/web/src/components/ToolActivity.tsx b/apps/web/src/components/ToolActivity.tsx
index fca6a759..442b44ab 100644
--- a/apps/web/src/components/ToolActivity.tsx
+++ b/apps/web/src/components/ToolActivity.tsx
@@ -1,12 +1,16 @@
+import { EXTERNAL_TOOL_PREFIX, isExternalToolName } from "@inkstone/protocol";
import {
AlertTriangle,
BookOpen,
Check,
+ ChevronRight,
+ ListChecks,
type LucideIcon,
Search,
Sparkles,
Wrench,
} from "lucide-react";
+import { useState } from "react";
import { cn } from "@/lib/utils.js";
import type { ToolCall } from "@/store/chat";
@@ -47,6 +51,12 @@ function humanize(name: string): string {
function presentation(name: string): ToolPresentation {
const known = TOOL_PRESENTATION[name];
if (known) return known;
+ if (isExternalToolName(name)) {
+ // An external (Worker-executed MCP) tool: label it by its TickTick verb
+ // (external-task-views A3/A4) — read-only by the dual allowlist.
+ const label = `TickTick · ${name.slice(EXTERNAL_TOOL_PREFIX.length).replace(/[_-]+/g, " ")}`;
+ return { active: label, done: label, Icon: ListChecks, access: "read" };
+ }
const label = humanize(name);
return { active: label, done: label, Icon: Wrench };
}
@@ -58,21 +68,26 @@ const MAX_VISIBLE_ARGS = 3;
* into one row, except errored calls — each is its own group so the failed arg
* is never buried in a survivors' row. `status` is the aggregate (running if any
* member is in flight). `args` is capped at {@link MAX_VISIBLE_ARGS}; `overflow`
- * is how many more were folded away. `key` is stable across renders. */
+ * is how many more were folded away. `key` is stable across renders. `call` is
+ * set ONLY for external (`ticktick_*`) break-outs (external-task-views A4): the
+ * single call the row represents, whose `result` the expansion reveals. */
export type ToolCallGroup = {
key: string;
name: string;
status: ToolCall["status"];
args: string[];
overflow: number;
+ call?: ToolCall;
};
/** Collapse a turn's tool calls into grouped rows (ADR-0043). Non-errored calls
* of the same tool merge (args deduped + joined, in first-seen order, status
- * running-if-any); each errored call breaks out into its own row. Groups are
- * ordered by first occurrence; a tool's errored break-out sorts at the position
- * of its first errored call. Shared by the live and rehydrated paths, so both
- * render identically. */
+ * running-if-any); each errored call breaks out into its own row. EXTERNAL
+ * (`ticktick_*`) calls NEVER group (external-task-views A4): one expandable row
+ * per call, keyed by `tool_call_id`, so two same-name calls keep their distinct
+ * results. Groups are ordered by first occurrence; a tool's errored break-out
+ * sorts at the position of its first errored call. Shared by the live and
+ * rehydrated paths, so both render identically. */
export function groupToolCalls(
toolCalls: readonly ToolCall[],
): ToolCallGroup[] {
@@ -83,6 +98,20 @@ export function groupToolCalls(
for (const call of toolCalls) {
const arg = call.arg?.trim() ? call.arg.trim() : undefined;
+ // External calls never merge (A4): per-call identity is the point — the
+ // row expands to THIS call's model-received result.
+ if (isExternalToolName(call.name)) {
+ groups.push({
+ key: call.id,
+ name: call.name,
+ status: call.status,
+ args: [],
+ overflow: 0,
+ call,
+ });
+ continue;
+ }
+
// Errored calls never merge — each is its own row showing the failed arg.
if (call.status === "error") {
groups.push({
@@ -140,13 +169,109 @@ export function ToolActivity({
aria-live="polite"
className="flex w-full flex-col gap-1.5"
>
- {groups.map((group) => (
-
- ))}
+ {groups.map((group) =>
+ group.call === undefined ? (
+
+ ) : (
+
+ ),
+ )}
);
}
+/** One EXTERNAL (`ticktick_*`) call (external-task-views A4): a collapsed
+ * name + status row that expands on demand to the normalized
+ * `TranscriptToolResult.content` the model received — errors identically
+ * (collapsed error row → expanded error content). Never grouped; never shows
+ * credentials or raw MCP metadata (the result IS the normalized content). */
+function ExternalToolRow({ call }: { call: ToolCall }) {
+ const [expanded, setExpanded] = useState(false);
+ const { active, done, Icon } = presentation(call.name);
+ const running = call.status === "running";
+ const errored = call.status === "error";
+ const label = running ? active : done;
+ const contentText = (call.result?.content ?? [])
+ .map((block) => block.text)
+ .join("\n");
+ const expandable = !running && call.result !== undefined;
+
+ const srText = running
+ ? `${active}, read-only, in progress`
+ : errored
+ ? `${done} failed`
+ : `${done}, read-only, done`;
+
+ return (
+
+
+ {expanded && expandable && (
+
+ {contentText}
+
+ )}
+
+ );
+}
+
function ToolCallRow({ group }: { group: ToolCallGroup }) {
const { active, done, Icon, access } = presentation(group.name);
const running = group.status === "running";
diff --git a/apps/web/src/components/library/TasksView.tsx b/apps/web/src/components/library/TasksView.tsx
new file mode 100644
index 00000000..060ec00c
--- /dev/null
+++ b/apps/web/src/components/library/TasksView.tsx
@@ -0,0 +1,220 @@
+import type { TickTickTaskRow } from "@inkstone/protocol";
+import { AlertTriangle, ListTodo, RefreshCw } from "lucide-react";
+import { useState } from "react";
+import { cn } from "@/lib/utils.js";
+
+// The Web Tasks surface (external-task-views A2/S2). Presentational — the route
+// owns the `useTickTick` hook (status-first + reconnect protocol) and passes
+// the resolved view here, so this renders without a runtime and is unit-tested
+// directly. NOT linked in nav (dev flag): reachable only at /library/tasks.
+
+/** A task's due tuple rendered for display: an all-day date, or the timed
+ * instant with its zone (S1a: one due tuple, never a bare instant). BOTH use
+ * `due.time_zone` — an all-day date rendered in UTC would show the previous
+ * calendar day for a positive-offset zone (e.g. Asia/Shanghai), so the local
+ * zone is the only correct frame. */
+function DueLabel({ due }: { due: NonNullable }) {
+ // TickTick's wire values are looser than Intl/Date accept (CodeRabbit #336):
+ // offsets come as non-ISO `+0000` (normalize to `+00:00` for `Date`) and the
+ // zone can be absent/empty (pass `undefined`, not `""` — an empty zone throws).
+ const date = new Date(due.date.replace(/([+-]\d{2})(\d{2})$/, "$1:$2"));
+ const timeZone = due.time_zone || undefined;
+ const text = due.is_all_day
+ ? date.toLocaleDateString(undefined, { timeZone })
+ : date.toLocaleString(undefined, { timeZone });
+ return {text};
+}
+
+function TaskRow({ task }: { task: TickTickTaskRow }) {
+ const done = task.checklist_items.filter((i) => i.done).length;
+ return (
+
+ );
+}
+
+export interface TasksViewProps {
+ readonly connected: boolean;
+ readonly statusResolved: boolean;
+ readonly statusError: boolean;
+ readonly rows: readonly TickTickTaskRow[];
+ readonly sourceLimitReached: boolean;
+ /** A first task read that failed with NO rows to show → the error state. */
+ readonly tasksInitialError: boolean;
+ /** A background refetch failed but the last-good rows are still held → keep
+ * rendering them with a stale indicator (A2 failure semantics). */
+ readonly tasksStaleError: boolean;
+ readonly tasksLoading: boolean;
+ /** Manual refresh (A2, review R12 #4): re-resolves status + re-reads tasks.
+ * Doubles as the retry affordance on the error states. */
+ readonly refresh: () => void;
+ readonly refreshing: boolean;
+}
+
+/** The Tasks surface body. Renders the not-connected / status-error /
+ * initial-error / loading states, the truncation warning when TickTick returned
+ * its 200-item ceiling, a STALE indicator when a background refetch failed (the
+ * rows are still shown), and the rows — with a LOCAL title filter (A2: any
+ * filtering the UI offers is display-only over the one fetched result). */
+export function TasksView({
+ connected,
+ statusResolved,
+ statusError,
+ rows,
+ sourceLimitReached,
+ tasksInitialError,
+ tasksStaleError,
+ tasksLoading,
+ refresh,
+ refreshing,
+}: TasksViewProps) {
+ const [filter, setFilter] = useState("");
+
+ const retry = (
+
+ );
+
+ // A status READ that failed (couldn't reach Core) is an error — distinct from
+ // a resolved `not_connected` state and from an empty task list.
+ if (statusError) {
+ return (
+
+ Couldn't reach TickTick. Check that Inkstone is running, then retry.
+ {retry}
+
+ TickTick is not connected. Provision a credential file and restart
+ Inkstone.
+
+ );
+ }
+ // A FIRST task read that failed with nothing cached → the error state. A
+ // failed BACKGROUND refetch (rows present) falls through and keeps the rows.
+ if (tasksInitialError) {
+ return (
+
+ Couldn't reach TickTick. Check that Inkstone is running, then retry.
+ {retry}
+
+
+ TickTick returned its 200-item limit; this view may be incomplete.
+
+ )}
+
+ {tasksStaleError && (
+
+
+ Couldn't refresh from TickTick; showing the last-loaded tasks.
+
+ )}
+
+ {tasksLoading || !statusResolved ? (
+ // `!statusResolved` here is the STATUS-PENDING phase (status-error and
+ // resolved-disconnected are handled above): show loading, never a false
+ // "No tasks." while the first status read is still in flight (review M5).
+
Loading tasks…
+ ) : visible.length === 0 ? (
+
No tasks.
+ ) : (
+
+ {visible.map((task) => (
+
+ ))}
+
+ )}
+
+ );
+}
diff --git a/apps/web/src/lib/hooks/useTickTick.ts b/apps/web/src/lib/hooks/useTickTick.ts
new file mode 100644
index 00000000..3a2b1cb5
--- /dev/null
+++ b/apps/web/src/lib/hooks/useTickTick.ts
@@ -0,0 +1,176 @@
+import type {
+ TickTickStatusResult,
+ TickTickTaskRow,
+ TickTickTasksListResult,
+} from "@inkstone/protocol";
+import { type ConnectionStatus, WsClient } from "@inkstone/ui-sdk";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { Effect, Fiber, Stream } from "effect";
+import { useCallback, useEffect, useState } from "react";
+import { useRuntime } from "@/runtime";
+
+// The Web lane's TanStack integration (external-task-views A2). The connection
+// ID is the SOLE task-query key: the fixed Core read (`{"status":[0]}` + kind
+// filtering) means one task query per connection, and any list/tag/date
+// filtering the Tasks UI offers is display-only, applied locally over that one
+// result. The reconnect purge is app-lifetime in `TickTickReconnectSync` (F2);
+// the hook here only reads.
+
+/** `["ticktick","tasks",]` — the task query key. The id alone
+ * keys it; a restart mints a new id (A5), so account B's rows can never land
+ * under account A's key. */
+const tasksKey = (connectionId: string) =>
+ ["ticktick", "tasks", connectionId] as const;
+
+const TASKS_KEY_PREFIX = ["ticktick", "tasks"] as const;
+const STATUS_KEY = ["ticktick", "status"] as const;
+
+/** Split a failed task read into an INITIAL failure (no successful fetch yet —
+ * `data` is `undefined`) vs. a STALE-refetch failure (a prior fetch's data,
+ * possibly an empty list, is retained by TanStack through the error). Keyed on
+ * `data === undefined`, NOT row count (review #4): a successful fetch of a
+ * genuinely empty account retains `{tasks: []}`, so its later refetch failure is
+ * STALE — keeping the empty view with an error hint — never a full initial-error
+ * screen. */
+export function classifyTasksError(
+ isError: boolean,
+ data: TickTickTasksListResult | undefined,
+): { tasksInitialError: boolean; tasksStaleError: boolean } {
+ return {
+ tasksInitialError: isError && data === undefined,
+ tasksStaleError: isError && data !== undefined,
+ };
+}
+
+/** App-lifetime WS-reconnect sync for the Web Tasks lane (A2, review F2). It MUST
+ * mount at the app ROOT, not inside the route: a Core restart (account swap) can
+ * happen while the Tasks view is UNMOUNTED, and a route-local effect would miss
+ * it — the remount would then trust the infinitely-fresh stale status/tasks cache
+ * and render account A under connection B. On a real RECONNECT edge
+ * (`(reconnecting|disconnected) → connected`, NOT a mount's replayed `connected`
+ * — ADR-0051 `.changes`) it drops every cached task query and `resetQueries`
+ * status, so the next status read mints the fresh id and the task read re-keys to
+ * the current account. Renders nothing. */
+export function TickTickReconnectSync(): null {
+ const runtime = useRuntime();
+ const queryClient = useQueryClient();
+
+ useEffect(() => {
+ const program = Effect.flatMap(WsClient, (client) => {
+ let prev: ConnectionStatus | undefined;
+ return Stream.runForEach(client.connectionStatus(), (state) =>
+ Effect.sync(() => {
+ const reconnected =
+ prev !== undefined && prev !== "connected" && state === "connected";
+ prev = state;
+ if (reconnected) {
+ queryClient.removeQueries({ queryKey: TASKS_KEY_PREFIX });
+ void queryClient.resetQueries({ queryKey: STATUS_KEY });
+ }
+ }),
+ );
+ });
+ const fiber = runtime.runFork(program);
+ return () => {
+ runtime.runFork(Fiber.interrupt(fiber));
+ };
+ }, [runtime, queryClient]);
+
+ return null;
+}
+
+/** The Web Tasks surface's data (A2). Status is its own query on the global
+ * staleTime; its `connection_id` is the SOLE task-query key. The reconnect purge
+ * lives app-lifetime in {@link TickTickReconnectSync} (a route-local one would
+ * miss a reconnect while Tasks is unmounted), so this hook only READS — a plain
+ * focus refetches the task list (60s staleTime), never status, and a plain mount
+ * purges nothing. After a reconnect reset, `connectionId` is `undefined` until the
+ * fresh id resolves, so the task read can never fire under a stale account's key. */
+export function useTickTick() {
+ const runtime = useRuntime();
+ const queryClient = useQueryClient();
+ const [manualRefreshing, setManualRefreshing] = useState(false);
+
+ const readStatus = useCallback(
+ () =>
+ runtime.runPromise(
+ Effect.flatMap(WsClient, (client) => client.tickTickStatus()),
+ ),
+ [runtime],
+ );
+ const readTasks = useCallback(
+ () =>
+ runtime.runPromise(
+ Effect.flatMap(WsClient, (client) => client.tickTickTasksList()),
+ ),
+ [runtime],
+ );
+
+ const status = useQuery({
+ queryKey: STATUS_KEY,
+ // Uses the global `staleTime: Infinity` (main.tsx). The account can only
+ // change across a Core restart, and the WS `connected` transition below
+ // RESETS this query then — NOT every window focus (review M4). A plain
+ // focus must never refetch status and blank the Tasks surface.
+ queryFn: readStatus,
+ });
+
+ // The connection ID keys the task read. It is `undefined` until status
+ // resolves `connected`; the app-lifetime `TickTickReconnectSync` reset clears
+ // `status.data` (→ `undefined` here → the task read disables) while a reconnect
+ // re-resolves, so a task fetch can never run under a stale id. No `isFetching`
+ // term — that dropped the id on every focus refetch and thrashed the cache (M4).
+ const connectionId =
+ status.data?.state === "connected" ? status.data.connection_id : undefined;
+
+ const tasks = useQuery({
+ queryKey: connectionId ? tasksKey(connectionId) : TASKS_KEY_PREFIX,
+ enabled: connectionId !== undefined,
+ staleTime: 60_000,
+ refetchOnWindowFocus: true,
+ refetchOnReconnect: true,
+ queryFn: readTasks,
+ });
+
+ const refresh = useCallback(() => {
+ setManualRefreshing(true);
+ queryClient.removeQueries({ queryKey: TASKS_KEY_PREFIX });
+
+ void queryClient
+ .resetQueries({ queryKey: STATUS_KEY, exact: true })
+ .then(() => {
+ const fresh =
+ queryClient.getQueryData(STATUS_KEY);
+ if (fresh?.state !== "connected") return;
+ return queryClient.fetchQuery({
+ queryKey: tasksKey(fresh.connection_id),
+ queryFn: readTasks,
+ staleTime: 0,
+ });
+ })
+ .catch(() => undefined)
+ .finally(() => {
+ setManualRefreshing(false);
+ });
+ }, [queryClient, readTasks]);
+
+ // #4: a FAILED background refetch keeps the last-good rows (TanStack retains
+ // `data` on error), so distinguish it from an initial failure with no rows.
+ const rows = (tasks.data?.tasks ?? []) as readonly TickTickTaskRow[];
+ return {
+ connected: status.data?.state === "connected",
+ statusResolved: status.isSuccess,
+ // A status read that FAILED (not merely disconnected) — the surface shows
+ // an error, not an empty "No tasks." list.
+ statusError: status.isError,
+ rows,
+ sourceLimitReached: tasks.data?.source_limit_reached ?? false,
+ // Initial-vs-stale failure split (review #4): see `classifyTasksError`.
+ ...classifyTasksError(tasks.isError, tasks.data),
+ tasksLoading: tasks.isLoading && connectionId !== undefined,
+ // Status-first manual refresh: task cache purge → fresh status → fresh-key
+ // task read. A disabled task observer is never refetched.
+ refresh,
+ refreshing: manualRefreshing || status.isFetching || tasks.isFetching,
+ };
+}
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 793f7966..0cdb3297 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -4,6 +4,7 @@ import { AlertTriangle, Compass } from "lucide-react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { EmptyState } from "./components/ui/empty-state.tsx";
+import { TickTickReconnectSync } from "./lib/hooks/useTickTick.ts";
import { routeTree } from "./routeTree.gen";
import { RuntimeProvider } from "./runtime.tsx";
import "./index.css";
@@ -89,6 +90,9 @@ createRoot(root).render(
+ {/* App-lifetime: observes WS reconnects even while Tasks is unmounted
+ (review F2), so an account swap can't survive in a stale cache. */}
+
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index a020b33e..4e206448 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -16,6 +16,7 @@ import { Route as LibraryIndexRouteImport } from './routes/library/index'
import { Route as ChatIndexRouteImport } from './routes/_chat/index'
import { Route as SettingsModelsRouteImport } from './routes/settings/models'
import { Route as LibraryTimelineRouteImport } from './routes/library/timeline'
+import { Route as LibraryTasksRouteImport } from './routes/library/tasks'
import { Route as LibraryMediaRouteImport } from './routes/library/media'
import { Route as LibraryHealthRouteImport } from './routes/library/health'
import { Route as LibraryGtdRouteImport } from './routes/library/gtd'
@@ -57,6 +58,11 @@ const LibraryTimelineRoute = LibraryTimelineRouteImport.update({
path: '/timeline',
getParentRoute: () => LibraryRouteRoute,
} as any)
+const LibraryTasksRoute = LibraryTasksRouteImport.update({
+ id: '/tasks',
+ path: '/tasks',
+ getParentRoute: () => LibraryRouteRoute,
+} as any)
const LibraryMediaRoute = LibraryMediaRouteImport.update({
id: '/media',
path: '/media',
@@ -97,6 +103,7 @@ export interface FileRoutesByFullPath {
'/library/gtd': typeof LibraryGtdRoute
'/library/health': typeof LibraryHealthRoute
'/library/media': typeof LibraryMediaRoute
+ '/library/tasks': typeof LibraryTasksRoute
'/library/timeline': typeof LibraryTimelineRoute
'/settings/models': typeof SettingsModelsRoute
'/library/': typeof LibraryIndexRoute
@@ -109,6 +116,7 @@ export interface FileRoutesByTo {
'/library/gtd': typeof LibraryGtdRoute
'/library/health': typeof LibraryHealthRoute
'/library/media': typeof LibraryMediaRoute
+ '/library/tasks': typeof LibraryTasksRoute
'/library/timeline': typeof LibraryTimelineRoute
'/settings/models': typeof SettingsModelsRoute
'/': typeof ChatIndexRoute
@@ -125,6 +133,7 @@ export interface FileRoutesById {
'/library/gtd': typeof LibraryGtdRoute
'/library/health': typeof LibraryHealthRoute
'/library/media': typeof LibraryMediaRoute
+ '/library/tasks': typeof LibraryTasksRoute
'/library/timeline': typeof LibraryTimelineRoute
'/settings/models': typeof SettingsModelsRoute
'/_chat/': typeof ChatIndexRoute
@@ -142,6 +151,7 @@ export interface FileRouteTypes {
| '/library/gtd'
| '/library/health'
| '/library/media'
+ | '/library/tasks'
| '/library/timeline'
| '/settings/models'
| '/library/'
@@ -154,6 +164,7 @@ export interface FileRouteTypes {
| '/library/gtd'
| '/library/health'
| '/library/media'
+ | '/library/tasks'
| '/library/timeline'
| '/settings/models'
| '/'
@@ -169,6 +180,7 @@ export interface FileRouteTypes {
| '/library/gtd'
| '/library/health'
| '/library/media'
+ | '/library/tasks'
| '/library/timeline'
| '/settings/models'
| '/_chat/'
@@ -233,6 +245,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof LibraryTimelineRouteImport
parentRoute: typeof LibraryRouteRoute
}
+ '/library/tasks': {
+ id: '/library/tasks'
+ path: '/tasks'
+ fullPath: '/library/tasks'
+ preLoaderRoute: typeof LibraryTasksRouteImport
+ parentRoute: typeof LibraryRouteRoute
+ }
'/library/media': {
id: '/library/media'
path: '/media'
@@ -283,6 +302,7 @@ interface LibraryRouteRouteChildren {
LibraryGtdRoute: typeof LibraryGtdRoute
LibraryHealthRoute: typeof LibraryHealthRoute
LibraryMediaRoute: typeof LibraryMediaRoute
+ LibraryTasksRoute: typeof LibraryTasksRoute
LibraryTimelineRoute: typeof LibraryTimelineRoute
LibraryIndexRoute: typeof LibraryIndexRoute
}
@@ -292,6 +312,7 @@ const LibraryRouteRouteChildren: LibraryRouteRouteChildren = {
LibraryGtdRoute: LibraryGtdRoute,
LibraryHealthRoute: LibraryHealthRoute,
LibraryMediaRoute: LibraryMediaRoute,
+ LibraryTasksRoute: LibraryTasksRoute,
LibraryTimelineRoute: LibraryTimelineRoute,
LibraryIndexRoute: LibraryIndexRoute,
}
diff --git a/apps/web/src/routes/library/tasks.tsx b/apps/web/src/routes/library/tasks.tsx
new file mode 100644
index 00000000..93e98614
--- /dev/null
+++ b/apps/web/src/routes/library/tasks.tsx
@@ -0,0 +1,16 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { TasksView } from "@/components/library/TasksView";
+import { useTickTick } from "@/lib/hooks/useTickTick";
+
+// The hidden Tasks surface (external-task-views S2). Reachable only by URL
+// (/library/tasks), deliberately NOT linked in TopicNav — the dev flag until
+// the S4 cutover promotes GTD → Tasks. The route owns the reconnect protocol
+// (via useTickTick); TasksView is the pure presentation.
+function TasksRoute() {
+ const view = useTickTick();
+ return ;
+}
+
+export const Route = createFileRoute("/library/tasks")({
+ component: TasksRoute,
+});
diff --git a/apps/web/src/store/bridge.ts b/apps/web/src/store/bridge.ts
index 17cedb48..12e94d8b 100644
--- a/apps/web/src/store/bridge.ts
+++ b/apps/web/src/store/bridge.ts
@@ -420,18 +420,21 @@ export async function awaitRun(
}
/**
- * Stop a Run from the chat surface (ADR-0014). Fires `run/cancel`, then settles
- * the UI off the authoritative response: interrupt the subscribe fiber, apply a
- * synthetic `cancelled` event to settle the bubble, and drop any pending Proposal.
+ * Stop a Run from the chat surface (ADR-0014). Fires `run/cancel`, then EITHER
+ * lets the live subscribe stream deliver the real terminal, OR settles the UI off
+ * the response — interrupt the fiber, apply a synthetic `cancelled` to settle the
+ * bubble, drop any pending Proposal.
*
- * We settle here for every (outcome, state) EXCEPT the one case whose terminal is
- * owned elsewhere — `already_terminal` on a *running* Run, where the live subscribe
- * stream already delivered (or will deliver) the real `done`/`error`/`cancelled`.
- * `accepted` settles (Core committed the cancel; for a running Run its real
- * `cancelled` is idempotent with the synthetic one). `unknown_run` settles (Core has
- * no run/hub, so NO stream event will ever come — bailing would leak the fiber). A
- * *parked* Run (awaiting a Proposal decision) has no live tail, so it settles on any
- * outcome rather than wedge the Stop control. See docs/design/web-store.md.
+ * The live stream OWNS the terminal (we return, settling nothing) in exactly two
+ * cases: `accepted` WITH a live tail — a running Run, whose real interrupted
+ * `tool_call`s + `cancelled` arrive on the hub this tab subscribes to (applying
+ * them is what keeps live == reload) — and `already_terminal` on a *running* Run
+ * (its real `done`/`error`/`cancelled` already came or will). Every other
+ * (outcome, state) settles off THIS response because no stream event will come: a
+ * *parked* Run (no live tail, any outcome), an `accepted` running Run WITHOUT a
+ * hub (the resume window), or `unknown_run` (no hub — bailing would leak the
+ * fiber). The inline conditions below are the authoritative table. See
+ * docs/design/web-store.md.
*/
export async function cancelRun(
runtime: WsRuntime,
@@ -440,8 +443,11 @@ export async function cancelRun(
const program = Effect.flatMap(WsClient, (client) => client.cancelRun(runId));
let outcome: "accepted" | "already_terminal" | "unknown_run";
+ let liveTail: boolean;
try {
- outcome = (await runtime.runPromise(program)).outcome;
+ const result = await runtime.runPromise(program);
+ outcome = result.outcome;
+ liveTail = result.live_tail;
} catch {
// Cancel is best-effort; a failed request leaves the Run as-is.
return;
@@ -452,33 +458,47 @@ export async function cancelRun(
return;
}
- // Parked-ness is a record field read, not re-derived from Proposal status: the
- // record stays `parked` from the moment a Proposal attaches through `deciding`
- // and a failed decide, flipping back to `running` only when the resume stream
- // re-subscribes (which then owns the terminal). A racing cancel during deciding
- // clears the Proposal here, and decideProposal's currency guard then bails.
+ // Parked-ness is a record field read (not re-derived from Proposal status):
+ // the record stays `parked` from proposal-attach through `deciding` and a
+ // failed decide, flipping to `running` only when the resume stream
+ // re-subscribes (which then owns the terminal).
const parked = isRunParked(runId);
- // The ONLY outcome whose terminal is owned elsewhere is `already_terminal` on a
- // non-parked Run: its live subscribe stream already delivered (or will deliver)
- // the real done/error/cancelled, which settles the bubble and reaps the fiber.
- // Every other case must settle here: `accepted` (Core committed the cancel),
- // and `unknown_run` (Core has no run/hub, so NO stream event will ever come —
- // bailing would leak the fiber and wedge Stop forever). `parked` always settles
- // since a parked Run has no live tail regardless of outcome.
- if (outcome === "already_terminal" && !parked) {
+ // `live_tail` (external-task-views A4) is Core's authoritative answer to "will
+ // a terminal reach me on the live stream?" — no timer guess. Leave the bubble
+ // to the live stream in exactly two cases:
+ // - `accepted` with `live_tail`: Core published (or will publish) the
+ // interrupted `tool_call` event(s) then `cancelled` on the hub this tab is
+ // subscribed to. The stream must APPLY them (interrupting here would drop an
+ // interrupted external call's result and diverge live from reload); its
+ // takeUntil(cancelled) reaps the fiber and fires onRunSettled.
+ // - `already_terminal` on a RUNNING Run: its live stream already delivered (or
+ // will deliver) the real done/error/cancelled.
+ if (
+ (outcome === "accepted" && liveTail) ||
+ (outcome === "already_terminal" && !parked)
+ ) {
return;
}
- // Interrupt first so the fiber's takeUntil can't race a real terminal event,
- // then settle deterministically off the authoritative cancel response.
+ // Everything else settles off this response — no stream event will come:
+ // parked (no live tail, any outcome), an `accepted` running-without-hub
+ // resume window, or `unknown_run` (no hub — bailing would leak the fiber).
+ settleCancelledLocally(runtime, threadId, runId);
+}
+
+/** The synthetic cancel settle: interrupt the fiber (so its takeUntil can't
+ * race), apply a local `cancelled`, drop any Proposal, and refresh the
+ * recent-Runs feed from this authoritative settle point (the interrupted
+ * fiber's own onRunSettled is identity-gated off). */
+function settleCancelledLocally(
+ runtime: WsRuntime,
+ threadId: string,
+ runId: RunId,
+): void {
interruptRun(runtime, runId);
applyEvent(threadId, runId, { kind: "cancelled" });
clearProposal(runId);
- // A cancel settles the Run HERE, not via the stream finalizer (which we just
- // interrupted — its onRunSettled is gated off precisely so resume/unmount
- // teardowns don't fire it). So refresh the recent-Runs feed from this
- // authoritative settle point, else a user-stopped Run lingers as Running/Waiting.
onRunSettled?.();
}
diff --git a/apps/web/src/store/chat.ts b/apps/web/src/store/chat.ts
index 47e277fb..2db81b81 100644
--- a/apps/web/src/store/chat.ts
+++ b/apps/web/src/store/chat.ts
@@ -2,45 +2,29 @@ import type { ProposalReviewContext, ResolvedNode } from "@inkstone/protocol";
import type { RunEventValue } from "@inkstone/ui-sdk";
import { useStore } from "zustand";
import { createStore } from "zustand/vanilla";
-
-/** A tool call surfaced live within an assistant turn (ADR-0006 tool_call Run Event). */
-export interface ToolCall {
- readonly id: string;
- readonly name: string;
- readonly status: "running" | "completed" | "error";
- /** The tool's display argument (ADR-0043), e.g. a search query; absent for argless tools. */
- readonly arg?: string;
-}
-
-/**
- * One item in an assistant turn's ordered timeline (ADR-0045): a contiguous run
- * of text, a tool-call boundary, a positional marker for the Proposal card, or a
- * `reasoning` (thinking) trace. The `proposal` segment carries ONLY `runId` — the
- * {@link PendingProposal} map stays the source of interactive state; this segment
- * just says "the card renders HERE in the timeline". The `reasoning` kind (ADR-0045
- * amendment, #202) is now realized — the model's thinking, default-collapsed, with
- * an optional `durationMs` (web-clocked live open→seal, Core-computed on reload). It
- * is EXCLUDED from {@link concatText}, so the trace never leaks into the reply text.
- * The `attachment` kind (ADR-0058) is an image on a user Message — the bytes live
- * at `GET /media/{mediaId}`; `width`/`height` are pixel dims when known. It carries
- * no text, so {@link concatText} excludes it by construction.
- */
-export type Segment =
- | { readonly kind: "text"; readonly text: string }
- | { readonly kind: "tool_call"; readonly call: ToolCall }
- | { readonly kind: "proposal"; readonly runId: string }
- | {
- readonly kind: "reasoning";
- readonly text: string;
- readonly durationMs?: number;
- }
- | {
- readonly kind: "attachment";
- readonly mediaId: string;
- readonly mime: string;
- readonly width?: number;
- readonly height?: number;
- };
+import {
+ appendProposalSegment,
+ appendReasoningSegment,
+ appendTextSegment,
+ concatText,
+ type Segment,
+ sealOpenReasoning,
+ settleRunningToolSegments,
+ type ToolCall,
+ toSegment,
+ upsertToolSegment,
+} from "./timeline.js";
+
+// The timeline model + its pure reducers live in ./timeline.ts (review F3);
+// re-export the public surface so existing `@/store/chat` importers (ToolCall,
+// Segment, concatText, toSegment, …) are unaffected by the split.
+export {
+ concatText,
+ type Segment,
+ type ToolCall,
+ toSegment,
+ type WireSegment,
+} from "./timeline.js";
/** The canonical live UI message; mirrors the wire `MessageView` shape. */
export interface Message {
@@ -71,17 +55,6 @@ export interface Message {
readonly cancelled?: boolean;
}
-/** Concatenate the text of every `text` segment in order — the single source for the
- * flat reply text the copy button, ⌘K search-match, typing-indicator, and retry read
- * (ADR-0045: there is no denormalized flat `text`; it derives from segments). */
-export function concatText(segments: readonly Segment[]): string {
- let text = "";
- for (const seg of segments) {
- if (seg.kind === "text") text += seg.text;
- }
- return text;
-}
-
/**
* Reactive hydrate-on-focus lifecycle (replaces the old non-reactive Set):
* `loading` while `thread/get` is in flight, `error` on a transient failed fetch
@@ -464,123 +437,6 @@ export function resetMessageForRetry(threadId: string, runId: string): void {
// The web mirror of Core's run_steps sequencer: each Run Event extends the ordered
// `segments[]` so the live render is the same shape the reload will read (slice 3).
-/**
- * Thread a `text_delta` into the timeline (ADR-0045), mirroring the flat-text
- * SET-vs-APPEND rule (ADR-0022) so `concatText(segments) === flat text` always holds:
- *
- * - **APPEND** (disarmed tail): extend the OPEN trailing text segment; if the trailing
- * segment is non-text (a tool/proposal just sealed the run) or the timeline is empty,
- * OPEN a fresh text segment — the web mirror of Core's open-on-first-delta.
- * - **SET** (armed cumulative snapshot): the delta is the cumulative concat of ALL the
- * turn's text so far (`group_concat`, no boundary markers — `select_run_snapshot`), so
- * it replaces EVERY existing text segment, not just the trailing one. Collapse all text
- * segments into ONE carrying the snapshot at the position of the FIRST text segment, and
- * drop the rest — PRESERVING the interleaved tool_call/proposal segments' order. If no
- * text segment exists yet, OPEN one at the end. Replacing only the last text segment (the
- * prior rule) left earlier text segments in place, so a post-park resume snapshot that
- * re-includes pre-park prose DUPLICATED it (concatText = "A" + "A B" ≠ flat "A B").
- */
-function appendTextSegment(
- segments: readonly Segment[],
- delta: string,
- armed: boolean,
-): readonly Segment[] {
- if (armed) {
- return setCumulativeText(segments, delta);
- }
- const last = segments[segments.length - 1];
- if (last?.kind === "text") {
- return [
- ...segments.slice(0, -1),
- { kind: "text", text: last.text + delta },
- ];
- }
- return [...segments, { kind: "text", text: delta }];
-}
-
-/**
- * Reconcile a cumulative-snapshot SET into the timeline: the snapshot is the WHOLE
- * turn's text, so the result has exactly one text segment carrying it (at the first
- * existing text position) and keeps every non-text segment in its place. With no text
- * segment yet, the snapshot opens one at the end. This is what makes
- * `concatText(segments) === snapshot` hold even when the turn had multiple pre-snapshot
- * text runs (text→tool→text→park→resume) — the duplicated-prefix case the prior
- * last-text-only rule missed.
- */
-function setCumulativeText(
- segments: readonly Segment[],
- snapshot: string,
-): readonly Segment[] {
- const firstTextIndex = segments.findIndex((seg) => seg.kind === "text");
- if (firstTextIndex === -1) {
- return [...segments, { kind: "text", text: snapshot }];
- }
- const result: Segment[] = [];
- for (let i = 0; i < segments.length; i++) {
- const seg = segments[i];
- if (i === firstTextIndex) {
- result.push({ kind: "text", text: snapshot });
- } else if (seg.kind !== "text") {
- result.push(seg);
- }
- // Drop every other text segment — its content is already in the snapshot.
- }
- return result;
-}
-
-/**
- * Thread a `reasoning_delta` into the timeline (ADR-0045 amendment): APPEND-ONLY,
- * the disarmed twin of {@link appendTextSegment}. There is NO armed cumulative-SET
- * path — the resume snapshot is text-only (`type='text'` SQL filter), so a reasoning
- * segment never receives a snapshot delta. If the trailing segment is `reasoning`,
- * extend its text (`opened: false`); else OPEN a fresh reasoning segment (`opened:
- * true`, the web mirror of Core's open-on-first-delta). A text/tool/proposal between
- * two reasoning runs correctly opens a new one. The `opened` flag is the single source
- * of "did a fresh block start here" — `applyEvent` uses it to (re)stamp the block's
- * open-time, rather than re-deriving the trailing-segment check separately.
- */
-function appendReasoningSegment(
- segments: readonly Segment[],
- delta: string,
-): { segments: readonly Segment[]; opened: boolean } {
- const last = segments[segments.length - 1];
- if (last?.kind === "reasoning") {
- return {
- segments: [
- ...segments.slice(0, -1),
- { kind: "reasoning", text: last.text + delta },
- ],
- opened: false,
- };
- }
- return {
- segments: [...segments, { kind: "reasoning", text: delta }],
- opened: true,
- };
-}
-
-/** Seal the OPEN trailing reasoning segment with a web-clocked `durationMs` when a Run
- * terminates (ADR-0045 amendment: live clocks its own open→seal). No-op if the trailing
- * segment is not reasoning, already sealed, or no open-time was recorded — the reloaded
- * path carries Core's authoritative `duration_ms`, so live is a nicety. */
-function sealOpenReasoning(
- segments: readonly Segment[],
- openedAt: number | undefined,
- now: number,
-): readonly Segment[] {
- if (openedAt === undefined) {
- return segments;
- }
- const last = segments[segments.length - 1];
- if (last?.kind !== "reasoning" || last.durationMs !== undefined) {
- return segments;
- }
- return [
- ...segments.slice(0, -1),
- { kind: "reasoning", text: last.text, durationMs: now - openedAt },
- ];
-}
-
/**
* A timeline boundary arrived for `runId` (a text delta, a new tool call, or the Run
* terminal): seal the open reasoning block with its web-clocked `durationMs` AND clear
@@ -616,51 +472,6 @@ function sealReasoningAtBoundary(
};
}
-/** Upsert a `tool_call` segment by call id (ADR-0045): a new id appends a fresh
- * segment at the end of the timeline; a known id flips its call's status in place. */
-function upsertToolSegment(
- segments: readonly Segment[],
- call: ToolCall,
-): readonly Segment[] {
- const found = segments.some(
- (seg) => seg.kind === "tool_call" && seg.call.id === call.id,
- );
- if (!found) {
- return [...segments, { kind: "tool_call", call }];
- }
- return segments.map((seg) =>
- seg.kind === "tool_call" && seg.call.id === call.id
- ? { kind: "tool_call", call: { ...seg.call, status: call.status } }
- : seg,
- );
-}
-
-/** Settle any `running` tool_call SEGMENT to `terminal` when its Run ends (the
- * segment-aware twin of {@link settleRunningToolCalls}; the lost-boundary case). */
-function settleRunningToolSegments(
- segments: readonly Segment[],
- terminal: "completed" | "error",
-): readonly Segment[] {
- return segments.map((seg) =>
- seg.kind === "tool_call" && seg.call.status === "running"
- ? { kind: "tool_call", call: { ...seg.call, status: terminal } }
- : seg,
- );
-}
-
-/** Append a `proposal` segment for `runId` at the current end of the timeline,
- * unless one is already present (skip-if-present): the seam where a Proposal enters
- * the timeline (it does NOT flow through {@link applyEvent}) — see {@link setPendingProposal}. */
-function appendProposalSegment(
- segments: readonly Segment[],
- runId: string,
-): readonly Segment[] {
- if (segments.some((seg) => seg.kind === "proposal")) {
- return segments;
- }
- return [...segments, { kind: "proposal", runId }];
-}
-
/** Attach a `proposal` segment (skip-if-present) to the assistant message owning
* `runId` within its thread — the {@link setPendingProposal} / {@link
* rehydrateDecidedProposal} timeline seam, shared so both enter the timeline identically.
@@ -766,6 +577,42 @@ export function applyEvent(
return s;
}
+ if (event.kind === "snapshot") {
+ // Full-timeline snapshot (review P1 #2): atomically REPLACE the run's
+ // segments with the ordered wire timeline (text / reasoning / tool_call
+ // in run_steps order, incl. a still-running call), then DISARM the
+ // cumulative-text bit so subsequent tail `text_delta`s APPEND to the
+ // snapshot rather than SET over it. This is the reconnect authority —
+ // it supersedes whatever `thread/get` painted, in true order.
+ const segments = event.segments.map((seg) => toSegment(runId, seg));
+ const next = updateRunMessage(s, threadId, runId, (m) => ({
+ ...m,
+ segments,
+ }));
+ const run = next.runs[runId];
+ if (run === undefined) {
+ return next;
+ }
+ // If the snapshot's timeline ENDS with an OPEN reasoning block
+ // (streaming, no `durationMs`), re-anchor `reasoningOpenedAt` so the next
+ // boundary can seal it — the wire snapshot carries no open-time, so
+ // without this the block stays unsealed forever (review F4). Any other
+ // trailing segment clears it. Re-anchoring to `now` times a post-reconnect
+ // seal from the snapshot — the best available once the true open-time is lost.
+ const last = segments[segments.length - 1];
+ const reasoningOpenedAt =
+ last?.kind === "reasoning" && last.durationMs === undefined
+ ? now
+ : undefined;
+ return {
+ ...next,
+ runs: {
+ ...next.runs,
+ [runId]: { ...run, snapshotArmed: false, reasoningOpenedAt },
+ },
+ };
+ }
+
if (event.kind === "text_delta") {
// A text delta means the model finished any open reasoning block: seal it
// with a web-clocked duration NOW (not at terminal) so the disclosure reads
@@ -830,13 +677,15 @@ export function applyEvent(
? sealReasoningAtBoundary(s, threadId, runId, now)
: s;
// Upsert into the timeline: `started` appends a `running` segment, a
- // terminal status flips the matching one in place (ADR-0045).
+ // terminal status flips the matching one in place (ADR-0045), merging
+ // the model-received `result` when the event carries one (A4).
const status = event.status === "started" ? "running" : event.status;
const call: ToolCall = {
id: event.tool_call_id,
name: event.name,
status,
arg: event.arg,
+ result: event.result,
};
return updateRunMessage(sealed, threadId, runId, (m) => ({
...m,
diff --git a/apps/web/src/store/hydrate.ts b/apps/web/src/store/hydrate.ts
index bbe27ed1..30df5c69 100644
--- a/apps/web/src/store/hydrate.ts
+++ b/apps/web/src/store/hydrate.ts
@@ -18,67 +18,9 @@ import {
rehydrateDecidedProposal,
type Segment,
setHydrationStatus,
+ toSegment,
} from "./chat.js";
-type WireSegment = ThreadGetResult["messages"][number]["segments"][number];
-
-/** A persisted tool call's wire status maps to a live `tool_call` segment status:
- * `error` keeps its spelling, anything else (a rehydrated call is `completed`)
- * settles to `completed`. A rehydrated call is never `running`. */
-function toToolCallStatus(status: string): "completed" | "error" {
- return status === "error" ? "error" : "completed";
-}
-
-/** Map one wire `Segment` to a live store {@link Segment} (ADR-0045), preserving
- * its timeline position. A `tool_call` segment carries no id (the durable record
- * has one, but the live row keys only on render order), so synthesize a stable
- * `:seg:` id from its index, keeping React keys distinct. The wire
- * `proposal` segment becomes a positional `{kind:"proposal", runId}` marker — the
- * decided card's interactive state lives in the `proposals` map, seeded separately
- * by {@link rehydrateDecidedProposals}. */
-function toSegment(
- messageId: string,
- runId: string,
- segment: WireSegment,
- index: number,
-): Segment {
- switch (segment.kind) {
- case "text":
- return { kind: "text", text: segment.text };
- case "tool_call":
- return {
- kind: "tool_call",
- call: {
- id: `${messageId}:seg:${index}`,
- name: segment.name,
- status: toToolCallStatus(segment.status),
- arg: segment.arg,
- },
- };
- case "proposal":
- return { kind: "proposal", runId };
- case "reasoning":
- // The model's thinking trace (ADR-0045 amendment): the wire carries Core's
- // computed `duration_ms`; store it as `durationMs`. Excluded from concatText.
- return {
- kind: "reasoning",
- text: segment.text,
- durationMs: segment.duration_ms,
- };
- case "attachment":
- // An image on a user Message (ADR-0058): the bytes live at
- // `GET /media/{media_id}`; `width`/`height` are omitted (not null) when the
- // upload didn't supply them. Carries no text, so concatText excludes it.
- return {
- kind: "attachment",
- mediaId: segment.media_id,
- mime: segment.mime,
- width: segment.width,
- height: segment.height,
- };
- }
-}
-
/** Map a wire `MessageView` to the live {@link Message}, narrowing role/status via
* defensive guards. The ordered `segments[]` is consumed VERBATIM (ADR-0045): the
* wire already carries the true `run_steps` order, so the reload renders the same
@@ -99,8 +41,8 @@ export function toMessage(view: ThreadGetResult["messages"][number]): Message {
// it must never be flagged.
const cancelled =
status === "incomplete" && view.terminal_reason === "cancelled";
- const segments: Segment[] = view.segments.map((segment, i) =>
- toSegment(view.id, view.run_id, segment, i),
+ const segments: Segment[] = view.segments.map((segment) =>
+ toSegment(view.run_id, segment),
);
return {
id: view.id,
diff --git a/apps/web/src/store/timeline.ts b/apps/web/src/store/timeline.ts
new file mode 100644
index 00000000..deb84679
--- /dev/null
+++ b/apps/web/src/store/timeline.ts
@@ -0,0 +1,289 @@
+import type { ThreadGetResult, TranscriptToolResult } from "@inkstone/protocol";
+
+// The assistant-turn TIMELINE model + its pure reducers (ADR-0045), extracted
+// from the Zustand store module (review F3): the wire→segment mapping and the
+// segment-array transforms that build a turn's ordered timeline. Every function
+// here is PURE over `Segment[]` — no store/`ChatState` dependency — so the store
+// module (`chat.ts`) owns only state wiring, and these reducers are unit-testable
+// in isolation. `chat.ts` re-exports the public types + `toSegment`/`concatText`
+// so existing `@/store/chat` importers are unaffected.
+
+/** A tool call surfaced live within an assistant turn (ADR-0006 tool_call Run Event). */
+export interface ToolCall {
+ readonly id: string;
+ readonly name: string;
+ readonly status: "running" | "completed" | "error";
+ /** The tool's display argument (ADR-0043), e.g. a search query; absent for argless tools. */
+ readonly arg?: string;
+ /** The normalized result the model received (external-task-views A4):
+ * carried on terminal events of external (`ticktick_*`) calls so the
+ * collapsed row can expand to it — identically live and after reload. */
+ readonly result?: TranscriptToolResult;
+}
+
+/**
+ * One item in an assistant turn's ordered timeline (ADR-0045): a contiguous run
+ * of text, a tool-call boundary, a positional marker for the Proposal card, or a
+ * `reasoning` (thinking) trace. The `proposal` segment carries ONLY `runId` — the
+ * {@link PendingProposal} map stays the source of interactive state; this segment
+ * just says "the card renders HERE in the timeline". The `reasoning` kind (ADR-0045
+ * amendment, #202) is now realized — the model's thinking, default-collapsed, with
+ * an optional `durationMs` (web-clocked live open→seal, Core-computed on reload). It
+ * is EXCLUDED from {@link concatText}, so the trace never leaks into the reply text.
+ * The `attachment` kind (ADR-0058) is an image on a user Message — the bytes live
+ * at `GET /media/{mediaId}`; `width`/`height` are pixel dims when known. It carries
+ * no text, so {@link concatText} excludes it by construction.
+ */
+export type Segment =
+ | { readonly kind: "text"; readonly text: string }
+ | { readonly kind: "tool_call"; readonly call: ToolCall }
+ | { readonly kind: "proposal"; readonly runId: string }
+ | {
+ readonly kind: "reasoning";
+ readonly text: string;
+ readonly durationMs?: number;
+ }
+ | {
+ readonly kind: "attachment";
+ readonly mediaId: string;
+ readonly mime: string;
+ readonly width?: number;
+ readonly height?: number;
+ };
+
+/** One wire `Segment` — from a `thread/get` result OR a `run/subscribe`
+ * `snapshot` Run Event (both carry the same `protocol::Segment`). */
+export type WireSegment =
+ ThreadGetResult["messages"][number]["segments"][number];
+
+/** A wire tool-call status → the live `tool_call` segment status. `running` (a
+ * live `snapshot`'s in-flight call, review P1 #2) and `error` keep their
+ * spelling; anything else (a rehydrated `thread/get` call is `completed`)
+ * settles to `completed`. */
+function toToolCallStatus(status: string): "running" | "completed" | "error" {
+ if (status === "running") return "running";
+ if (status === "error") return "error";
+ return "completed";
+}
+
+/** Map one wire `Segment` to a live store {@link Segment} (ADR-0045), preserving
+ * its timeline position — SHARED by `thread/get` rehydration and the
+ * `run/subscribe` `snapshot` event (review P1 #2). A `tool_call` keys on the
+ * durable `tool_call_id` (external-task-views A4) and carries the model-received
+ * `result`; a wire `proposal` becomes a positional `{kind:"proposal", runId}`
+ * marker (its interactive state lives in the `proposals` map, seeded separately). */
+export function toSegment(runId: string, segment: WireSegment): Segment {
+ switch (segment.kind) {
+ case "text":
+ return { kind: "text", text: segment.text };
+ case "tool_call":
+ return {
+ kind: "tool_call",
+ call: {
+ id: segment.tool_call_id,
+ name: segment.name,
+ status: toToolCallStatus(segment.status),
+ arg: segment.arg,
+ result: segment.result,
+ },
+ };
+ case "proposal":
+ return { kind: "proposal", runId };
+ case "reasoning":
+ return {
+ kind: "reasoning",
+ text: segment.text,
+ durationMs: segment.duration_ms,
+ };
+ case "attachment":
+ return {
+ kind: "attachment",
+ mediaId: segment.media_id,
+ mime: segment.mime,
+ width: segment.width,
+ height: segment.height,
+ };
+ }
+}
+
+/** Concatenate the text of every `text` segment in order — the single source for the
+ * flat reply text the copy button, ⌘K search-match, typing-indicator, and retry read
+ * (ADR-0045: there is no denormalized flat `text`; it derives from segments). */
+export function concatText(segments: readonly Segment[]): string {
+ let text = "";
+ for (const seg of segments) {
+ if (seg.kind === "text") text += seg.text;
+ }
+ return text;
+}
+
+/**
+ * Thread a `text_delta` into the timeline (ADR-0045), mirroring the flat-text
+ * SET-vs-APPEND rule (ADR-0022) so `concatText(segments) === flat text` always holds:
+ *
+ * - **APPEND** (disarmed tail): extend the OPEN trailing text segment; if the trailing
+ * segment is non-text (a tool/proposal just sealed the run) or the timeline is empty,
+ * OPEN a fresh text segment — the web mirror of Core's open-on-first-delta.
+ * - **SET** (armed cumulative snapshot): the delta is the cumulative concat of ALL the
+ * turn's text so far (`group_concat`, no boundary markers — `select_run_snapshot`), so
+ * it replaces EVERY existing text segment, not just the trailing one. Collapse all text
+ * segments into ONE carrying the snapshot at the position of the FIRST text segment, and
+ * drop the rest — PRESERVING the interleaved tool_call/proposal segments' order. If no
+ * text segment exists yet, OPEN one at the end. Replacing only the last text segment (the
+ * prior rule) left earlier text segments in place, so a post-park resume snapshot that
+ * re-includes pre-park prose DUPLICATED it (concatText = "A" + "A B" ≠ flat "A B").
+ */
+export function appendTextSegment(
+ segments: readonly Segment[],
+ delta: string,
+ armed: boolean,
+): readonly Segment[] {
+ if (armed) {
+ return setCumulativeText(segments, delta);
+ }
+ const last = segments[segments.length - 1];
+ if (last?.kind === "text") {
+ return [
+ ...segments.slice(0, -1),
+ { kind: "text", text: last.text + delta },
+ ];
+ }
+ return [...segments, { kind: "text", text: delta }];
+}
+
+/**
+ * Reconcile a cumulative-snapshot SET into the timeline: the snapshot is the WHOLE
+ * turn's text, so the result has exactly one text segment carrying it (at the first
+ * existing text position) and keeps every non-text segment in its place. With no text
+ * segment yet, the snapshot opens one at the end. This is what makes
+ * `concatText(segments) === snapshot` hold even when the turn had multiple pre-snapshot
+ * text runs (text→tool→text→park→resume) — the duplicated-prefix case the prior
+ * last-text-only rule missed.
+ */
+function setCumulativeText(
+ segments: readonly Segment[],
+ snapshot: string,
+): readonly Segment[] {
+ const firstTextIndex = segments.findIndex((seg) => seg.kind === "text");
+ if (firstTextIndex === -1) {
+ return [...segments, { kind: "text", text: snapshot }];
+ }
+ const result: Segment[] = [];
+ for (let i = 0; i < segments.length; i++) {
+ const seg = segments[i];
+ if (i === firstTextIndex) {
+ result.push({ kind: "text", text: snapshot });
+ } else if (seg.kind !== "text") {
+ result.push(seg);
+ }
+ // Drop every other text segment — its content is already in the snapshot.
+ }
+ return result;
+}
+
+/**
+ * Thread a `reasoning_delta` into the timeline (ADR-0045 amendment): APPEND-ONLY,
+ * the disarmed twin of {@link appendTextSegment}. There is NO armed cumulative-SET
+ * path — the resume snapshot is text-only (`type='text'` SQL filter), so a reasoning
+ * segment never receives a snapshot delta. If the trailing segment is `reasoning`,
+ * extend its text (`opened: false`); else OPEN a fresh reasoning segment (`opened:
+ * true`, the web mirror of Core's open-on-first-delta). A text/tool/proposal between
+ * two reasoning runs correctly opens a new one. The `opened` flag is the single source
+ * of "did a fresh block start here" — `applyEvent` uses it to (re)stamp the block's
+ * open-time, rather than re-deriving the trailing-segment check separately.
+ */
+export function appendReasoningSegment(
+ segments: readonly Segment[],
+ delta: string,
+): { segments: readonly Segment[]; opened: boolean } {
+ const last = segments[segments.length - 1];
+ if (last?.kind === "reasoning") {
+ return {
+ segments: [
+ ...segments.slice(0, -1),
+ { kind: "reasoning", text: last.text + delta },
+ ],
+ opened: false,
+ };
+ }
+ return {
+ segments: [...segments, { kind: "reasoning", text: delta }],
+ opened: true,
+ };
+}
+
+/** Seal the OPEN trailing reasoning segment with a web-clocked `durationMs` when a Run
+ * terminates (ADR-0045 amendment: live clocks its own open→seal). No-op if the trailing
+ * segment is not reasoning, already sealed, or no open-time was recorded — the reloaded
+ * path carries Core's authoritative `duration_ms`, so live is a nicety. */
+export function sealOpenReasoning(
+ segments: readonly Segment[],
+ openedAt: number | undefined,
+ now: number,
+): readonly Segment[] {
+ if (openedAt === undefined) {
+ return segments;
+ }
+ const last = segments[segments.length - 1];
+ if (last?.kind !== "reasoning" || last.durationMs !== undefined) {
+ return segments;
+ }
+ return [
+ ...segments.slice(0, -1),
+ { kind: "reasoning", text: last.text, durationMs: now - openedAt },
+ ];
+}
+
+/** Upsert a `tool_call` segment by call id (ADR-0045): a new id appends a fresh
+ * segment at the end of the timeline; a known id merges the terminal `status`
+ * AND `result` into the existing call in place (external-task-views A4 — the
+ * started row keeps its fields; the terminal event settles them). */
+export function upsertToolSegment(
+ segments: readonly Segment[],
+ call: ToolCall,
+): readonly Segment[] {
+ const found = segments.some(
+ (seg) => seg.kind === "tool_call" && seg.call.id === call.id,
+ );
+ if (!found) {
+ return [...segments, { kind: "tool_call", call }];
+ }
+ return segments.map((seg) =>
+ seg.kind === "tool_call" && seg.call.id === call.id
+ ? {
+ kind: "tool_call",
+ call: {
+ ...seg.call,
+ status: call.status,
+ ...(call.result === undefined ? {} : { result: call.result }),
+ },
+ }
+ : seg,
+ );
+}
+
+/** Settle any `running` tool_call SEGMENT to `terminal` when its Run ends (the
+ * segment-aware twin of `settleRunningToolCalls`; the lost-boundary case). */
+export function settleRunningToolSegments(
+ segments: readonly Segment[],
+ terminal: "completed" | "error",
+): readonly Segment[] {
+ return segments.map((seg) =>
+ seg.kind === "tool_call" && seg.call.status === "running"
+ ? { kind: "tool_call", call: { ...seg.call, status: terminal } }
+ : seg,
+ );
+}
+
+/** Append a `proposal` segment for `runId` at the current end of the timeline,
+ * unless one is already present (skip-if-present): the seam where a Proposal enters
+ * the timeline (it does NOT flow through `applyEvent`) — see `setPendingProposal`. */
+export function appendProposalSegment(
+ segments: readonly Segment[],
+ runId: string,
+): readonly Segment[] {
+ if (segments.some((seg) => seg.kind === "proposal")) {
+ return segments;
+ }
+ return [...segments, { kind: "proposal", runId }];
+}
diff --git a/apps/web/test/components/ChatColumn.test.tsx b/apps/web/test/components/ChatColumn.test.tsx
index 46b71c7b..26bf7cb6 100644
--- a/apps/web/test/components/ChatColumn.test.tsx
+++ b/apps/web/test/components/ChatColumn.test.tsx
@@ -14,7 +14,7 @@ import {
} from "@test/test-utils/renderWithCore";
import { act, cleanup, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
-import { Deferred, Effect, Stream } from "effect";
+import { Deferred, Effect, Queue, Stream } from "effect";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ChatColumn } from "@/components/ChatColumn.js";
import {
@@ -66,7 +66,8 @@ function makeStubOverrides(opts: {
subscribeRun: () => Stream.fromIterable(opts.events),
cancelRun:
opts.cancelRun ??
- (() => Effect.succeed({ outcome: "accepted" as const })),
+ (() =>
+ Effect.succeed({ outcome: "accepted" as const, live_tail: false })),
// Fail fast on an UNEXPECTED retry path: a test that drives run/retry must
// opt in via `opts.retryRun`; an accidental retry in an unrelated test dies
// rather than silently passing on a default "accepted" (CodeRabbit #244).
@@ -857,17 +858,33 @@ describe("ChatColumn", () => {
it("shows a Stop control while a run streams and settles the bubble on cancel", async () => {
const user = userEvent.setup();
+ // The stream stays OPEN after the partial delta (a live tail), and — per
+ // the A4 cancel contract — Core delivers the real `cancelled` event right
+ // behind an accepted response; the bridge now applies THAT instead of
+ // synthesizing its own (which would clobber interrupted tool results).
+ const tail = Effect.runSync(Queue.unbounded());
const cancelRun = vi.fn(() =>
- Effect.succeed({ outcome: "accepted" as const }),
+ Effect.sync(() => {
+ Queue.unsafeOffer(tail, { kind: "cancelled" } as RunEventValue);
+ // live_tail: true — the live stream delivers the real `cancelled`.
+ return { outcome: "accepted" as const, live_tail: true };
+ }),
);
- // A partial (non-terminal) stream: the assistant turn stays active (no
- // done/error/cancelled), so activeRunId stays set and Stop is shown.
- const overrides = makeStubOverrides({
- runId: "run-stop",
- threadId: "thread-stop",
- events: [{ kind: "text_delta", delta: "echo: h" }],
- cancelRun,
- });
+ const overrides = {
+ ...makeStubOverrides({
+ runId: "run-stop",
+ threadId: "thread-stop",
+ events: [],
+ cancelRun,
+ }),
+ subscribeRun: () =>
+ Stream.concat(
+ Stream.fromIterable([
+ { kind: "text_delta", delta: "echo: h" } as RunEventValue,
+ ]),
+ Stream.fromQueue(tail),
+ ),
+ };
await renderFocused(overrides, "threadA");
diff --git a/apps/web/test/components/ToolActivity.test.tsx b/apps/web/test/components/ToolActivity.test.tsx
index 06538c02..b7784dd4 100644
--- a/apps/web/test/components/ToolActivity.test.tsx
+++ b/apps/web/test/components/ToolActivity.test.tsx
@@ -1,4 +1,5 @@
import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
import { afterEach, describe, expect, it } from "vitest";
import { groupToolCalls, ToolActivity } from "@/components/ToolActivity.js";
import type { ToolCall } from "@/store/chat";
@@ -143,3 +144,115 @@ describe("ToolActivity grouped rendering", () => {
expect(row).toHaveTextContent("+1");
});
});
+
+// ── External (`ticktick_*`) calls — external-task-views A4 ──────────────────
+
+const externalResult = (text: string, isError = false) => ({
+ content: [{ type: "text" as const, text }],
+ is_error: isError,
+});
+
+describe("external calls never group", () => {
+ it("two same-name external calls stay two rows, keyed by call id, results distinct", () => {
+ const groups = groupToolCalls([
+ call({
+ id: "tc_a",
+ name: "ticktick_search_task",
+ result: externalResult("first result"),
+ }),
+ call({
+ id: "tc_b",
+ name: "ticktick_search_task",
+ result: externalResult("second result"),
+ }),
+ ]);
+ expect(groups).toHaveLength(2);
+ expect(groups.map((g) => g.key)).toEqual(["tc_a", "tc_b"]);
+ expect(groups[0].call?.result?.content[0].text).toBe("first result");
+ expect(groups[1].call?.result?.content[0].text).toBe("second result");
+ });
+
+ it("an external call never merges into a same-position Core group", () => {
+ const groups = groupToolCalls([
+ call({ id: "1", arg: "Lev" }),
+ call({ id: "tc_ext", name: "ticktick_filter_tasks" }),
+ call({ id: "2", arg: "Acme" }),
+ ]);
+ // Core calls still merge around it; the external row keeps its slot.
+ expect(groups.map((g) => g.key)).toEqual([
+ "group:search_entities",
+ "tc_ext",
+ ]);
+ expect(groups[1].call?.name).toBe("ticktick_filter_tasks");
+ });
+});
+
+describe("external expandable row", () => {
+ it("renders collapsed, expands to the model-received content, and collapses back", async () => {
+ render(
+ ,
+ );
+ const row = screen.getByTestId("tool-call");
+ expect(row).toHaveAttribute("data-status", "completed");
+ // Collapsed by default: the content is NOT in the document.
+ expect(screen.queryByTestId("tool-call-result")).toBeNull();
+
+ const toggle = screen.getByRole("button");
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ await userEvent.click(toggle);
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(screen.getByTestId("tool-call-result")).toHaveTextContent(
+ "1 task found: S1 timed",
+ );
+
+ await userEvent.click(toggle);
+ expect(screen.queryByTestId("tool-call-result")).toBeNull();
+ });
+
+ it("an errored external call renders the error row and expands to the error content — identically", async () => {
+ render(
+ ,
+ );
+ const row = screen.getByTestId("tool-call");
+ expect(row).toHaveAttribute("data-status", "error");
+ expect(row).toHaveTextContent("failed");
+
+ await userEvent.click(screen.getByRole("button"));
+ expect(screen.getByTestId("tool-call-result")).toHaveTextContent(
+ "interrupted",
+ );
+ });
+
+ it("a running external row is not expandable yet (no result)", () => {
+ render(
+ ,
+ );
+ expect(screen.getByRole("button")).toBeDisabled();
+ expect(screen.queryByTestId("tool-call-result")).toBeNull();
+ });
+});
diff --git a/apps/web/test/components/library/TasksView.test.tsx b/apps/web/test/components/library/TasksView.test.tsx
new file mode 100644
index 00000000..9141cd6d
--- /dev/null
+++ b/apps/web/test/components/library/TasksView.test.tsx
@@ -0,0 +1,228 @@
+import type { TickTickTaskRow } from "@inkstone/protocol";
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it } from "vitest";
+import { TasksView, type TasksViewProps } from "@/components/library/TasksView";
+
+afterEach(cleanup);
+
+function row(
+ partial: Partial & { id: string },
+): TickTickTaskRow {
+ return {
+ title: "a task",
+ kind: "TEXT",
+ priority: 0,
+ tags: [],
+ checklist_items: [],
+ ...partial,
+ };
+}
+
+function view(overrides: Partial = {}): TasksViewProps {
+ return {
+ connected: true,
+ statusResolved: true,
+ statusError: false,
+ rows: [],
+ sourceLimitReached: false,
+ tasksInitialError: false,
+ tasksStaleError: false,
+ tasksLoading: false,
+ refresh: () => {},
+ refreshing: false,
+ ...overrides,
+ };
+}
+
+describe("TasksView", () => {
+ it("shows the not-connected notice when status resolved disconnected", () => {
+ render();
+ expect(screen.getByTestId("ticktick-disconnected")).toBeInTheDocument();
+ });
+
+ it("shows the error state on a status-read failure (not 'No tasks.')", () => {
+ render(
+ ,
+ );
+ expect(screen.getByTestId("ticktick-error")).toBeInTheDocument();
+ expect(screen.queryByText("No tasks.")).toBeNull();
+ });
+
+ it("an INITIAL task failure (no rows) shows the error state", () => {
+ render();
+ expect(screen.getByTestId("ticktick-error")).toBeInTheDocument();
+ });
+
+ it("offers a manual refresh that fires the command (A2, review R12 #4)", async () => {
+ let refreshed = 0;
+ render(
+ {
+ refreshed += 1;
+ },
+ })}
+ />,
+ );
+ await userEvent.click(screen.getByTestId("ticktick-refresh"));
+ expect(refreshed).toBe(1);
+ });
+
+ it("disables the refresh control while a refresh is in flight", () => {
+ render(
+ ,
+ );
+ expect(screen.getByTestId("ticktick-refresh")).toBeDisabled();
+ });
+
+ it("the error states offer a Retry that fires the refresh command", async () => {
+ let refreshed = 0;
+ render(
+ {
+ refreshed += 1;
+ },
+ })}
+ />,
+ );
+ await userEvent.click(screen.getByRole("button", { name: "Retry" }));
+ expect(refreshed).toBe(1);
+ });
+
+ it("shows loading (never a false 'No tasks.') while the status read is pending", () => {
+ // The first status fetch is in flight: not resolved, not connected, no rows,
+ // no task-loading flag yet (the task read is still gated) — review M5.
+ render(
+ ,
+ );
+ expect(screen.getByText("Loading tasks…")).toBeInTheDocument();
+ expect(screen.queryByText("No tasks.")).toBeNull();
+ });
+
+ it("a STALE refetch failure keeps the last-good rows with a stale indicator", () => {
+ render(
+ ,
+ );
+ // The rows survive a failed background refetch (A2 failure semantics)…
+ expect(screen.getByTestId("ticktick-task")).toHaveTextContent("buy milk");
+ // …with a stale indicator, NOT the full error screen.
+ expect(screen.getByTestId("ticktick-stale-warning")).toBeInTheDocument();
+ expect(screen.queryByTestId("ticktick-error")).toBeNull();
+ });
+
+ it("renders the truncation warning ONLY when the source limit was reached", () => {
+ const { rerender } = render(
+ ,
+ );
+ expect(screen.queryByTestId("ticktick-truncation-warning")).toBeNull();
+
+ rerender(
+ ,
+ );
+ expect(screen.getByTestId("ticktick-truncation-warning")).toHaveTextContent(
+ "200-item limit",
+ );
+ });
+
+ it("renders one row per task, with an unmatched list shown as 'unnamed list'", () => {
+ render(
+ ,
+ );
+ const rows = screen.getAllByTestId("ticktick-task");
+ expect(rows).toHaveLength(2);
+ expect(rows[0]).toHaveTextContent("buy milk");
+ expect(rows[0]).toHaveTextContent("Inbox");
+ expect(rows[1]).toHaveTextContent("unnamed list");
+ });
+
+ it("filters LOCALLY by title over the one fetched result (A2 display-only filtering)", async () => {
+ const user = userEvent.setup();
+ render(
+ ,
+ );
+ expect(screen.getAllByTestId("ticktick-task")).toHaveLength(2);
+ await user.type(
+ screen.getByRole("searchbox", { name: /filter tasks/i }),
+ "milk",
+ );
+ const rows = screen.getAllByTestId("ticktick-task");
+ expect(rows).toHaveLength(1);
+ expect(rows[0]).toHaveTextContent("buy milk");
+ });
+
+ it("renders an all-day due in its own timezone, not UTC (Asia/Shanghai regression)", () => {
+ // An all-day 2026-08-20 in Asia/Shanghai (+8) is stored as the UTC instant
+ // of local midnight: 2026-08-19T16:00:00Z. Formatting in UTC would show
+ // Aug 19 (the previous day); the local zone must show Aug 20.
+ const date = "2026-08-19T16:00:00.000+0000";
+ render(
+ ,
+ );
+ const rowText = screen.getByTestId("ticktick-task").textContent ?? "";
+ const shanghai = new Date(date).toLocaleDateString(undefined, {
+ timeZone: "Asia/Shanghai",
+ });
+ const utc = new Date(date).toLocaleDateString(undefined, {
+ timeZone: "UTC",
+ });
+ expect(shanghai).not.toBe(utc); // the two zones disagree on the calendar day
+ expect(rowText).toContain(shanghai);
+ expect(rowText).not.toContain(utc);
+ });
+
+ it("shows a checklist progress count", () => {
+ render(
+ ,
+ );
+ expect(screen.getByTestId("ticktick-task")).toHaveTextContent("1/2");
+ });
+});
diff --git a/apps/web/test/lib/hooks/useTickTick.test.tsx b/apps/web/test/lib/hooks/useTickTick.test.tsx
new file mode 100644
index 00000000..899db86e
--- /dev/null
+++ b/apps/web/test/lib/hooks/useTickTick.test.tsx
@@ -0,0 +1,341 @@
+import type {
+ TickTickStatusResult,
+ TickTickTasksListResult,
+} from "@inkstone/protocol";
+import type { ConnectionStatus } from "@inkstone/ui-sdk";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { makeCoreRuntime } from "@test/test-utils/renderWithCore";
+import { act, render, renderHook, waitFor } from "@testing-library/react";
+import { Effect, Queue, Stream } from "effect";
+import type { ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import {
+ classifyTasksError,
+ TickTickReconnectSync,
+ useTickTick,
+} from "@/lib/hooks/useTickTick.js";
+import { RuntimeProvider } from "@/runtime";
+
+// The A2 reconnect protocol splits across two homes: `useTickTick` GATES the task
+// read on the connection id, and the app-lifetime `TickTickReconnectSync` PURGES
+// the cache on a real WS reconnect edge — NOT a mount's replayed `connected`
+// (review F2/F5). Both are pinned here, deterministically (no stream timing).
+
+function wrapper(opts: {
+ status?: TickTickStatusResult;
+ tasks?: TickTickTasksListResult;
+ statusRead?: () => Effect.Effect;
+ tasksRead?: () => Effect.Effect;
+ onTasksCall?: () => void;
+ connectionStatus?: Stream.Stream;
+ queryClient: QueryClient;
+}) {
+ const connectionStatus = opts.connectionStatus;
+ const runtime = makeCoreRuntime({
+ overrides: {
+ tickTickStatus:
+ opts.statusRead ??
+ (() => Effect.succeed(opts.status ?? { state: "not_connected" })),
+ tickTickTasksList: () =>
+ Effect.suspend(() => {
+ opts.onTasksCall?.();
+ return (
+ opts.tasksRead?.() ??
+ Effect.succeed(
+ opts.tasks ?? { tasks: [], source_limit_reached: false },
+ )
+ );
+ }),
+ ...(connectionStatus ? { connectionStatus: () => connectionStatus } : {}),
+ },
+ });
+ return ({ children }: { children: ReactNode }) => (
+
+ {children}
+
+ );
+}
+
+const task = (id: string, title: string) => ({
+ id,
+ title,
+ kind: "TEXT" as const,
+ priority: 0,
+ tags: [],
+ checklist_items: [],
+});
+
+describe("useTickTick task-read gating", () => {
+ it("gates the task read on a known connection id (never fetches while not connected)", async () => {
+ let tasksCalls = 0;
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const { result } = renderHook(() => useTickTick(), {
+ wrapper: wrapper({
+ status: { state: "not_connected" },
+ onTasksCall: () => {
+ tasksCalls += 1;
+ },
+ queryClient,
+ }),
+ });
+
+ await waitFor(() => expect(result.current.statusResolved).toBe(true));
+ expect(result.current.connected).toBe(false);
+ // The task read is `enabled` only once an id is known — it never fired.
+ expect(tasksCalls).toBe(0);
+ expect(result.current.rows).toEqual([]);
+ });
+
+ it("a retry from disconnected awaits fresh status and then fetches the fresh key", async () => {
+ let statusCalls = 0;
+ let tasksCalls = 0;
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const { result } = renderHook(() => useTickTick(), {
+ wrapper: wrapper({
+ statusRead: () =>
+ Effect.sync(() => {
+ statusCalls += 1;
+ return statusCalls === 1
+ ? ({ state: "not_connected" } as const)
+ : ({ state: "connected", connection_id: "acct-B" } as const);
+ }),
+ tasksRead: () =>
+ Effect.sync(() => {
+ tasksCalls += 1;
+ return {
+ tasks: [task("b-1", "B task")],
+ source_limit_reached: false,
+ };
+ }),
+ queryClient,
+ }),
+ });
+
+ await waitFor(() => expect(result.current.statusResolved).toBe(true));
+ expect(result.current.connected).toBe(false);
+ expect(tasksCalls).toBe(0);
+
+ act(() => result.current.refresh());
+
+ await waitFor(() =>
+ expect(result.current.rows.map((row) => row.id)).toEqual(["b-1"]),
+ );
+ expect(statusCalls).toBe(2);
+ expect(tasksCalls).toBe(1);
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-B"]),
+ ).toMatchObject({ tasks: [{ id: "b-1" }] });
+ });
+
+ it("clears account A immediately and waits for delayed account B status before fetching", async () => {
+ let resolveFreshStatus!: (status: TickTickStatusResult) => void;
+ const freshStatus = new Promise((resolve) => {
+ resolveFreshStatus = resolve;
+ });
+ let statusCalls = 0;
+ let tasksCalls = 0;
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ const { result } = renderHook(() => useTickTick(), {
+ wrapper: wrapper({
+ statusRead: () => {
+ statusCalls += 1;
+ return statusCalls === 1
+ ? Effect.succeed({
+ state: "connected",
+ connection_id: "acct-A",
+ } as const)
+ : Effect.promise(() => freshStatus);
+ },
+ tasksRead: () =>
+ Effect.sync(() => {
+ tasksCalls += 1;
+ return tasksCalls === 1
+ ? {
+ tasks: [task("a-1", "A task")],
+ source_limit_reached: false,
+ }
+ : {
+ tasks: [task("b-1", "B task")],
+ source_limit_reached: false,
+ };
+ }),
+ queryClient,
+ }),
+ });
+
+ await waitFor(() =>
+ expect(result.current.rows.map((row) => row.id)).toEqual(["a-1"]),
+ );
+ expect(tasksCalls).toBe(1);
+
+ act(() => result.current.refresh());
+
+ await waitFor(() => expect(result.current.rows).toEqual([]));
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-A"]),
+ ).toBeUndefined();
+ expect(tasksCalls).toBe(1);
+ expect(result.current.refreshing).toBe(true);
+
+ await act(async () => {
+ resolveFreshStatus({
+ state: "connected",
+ connection_id: "acct-B",
+ });
+ await freshStatus;
+ });
+
+ await waitFor(() =>
+ expect(result.current.rows.map((row) => row.id)).toEqual(["b-1"]),
+ );
+ expect(statusCalls).toBe(2);
+ expect(tasksCalls).toBe(2);
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-A"]),
+ ).toBeUndefined();
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-B"]),
+ ).toMatchObject({ tasks: [{ id: "b-1" }] });
+ });
+});
+
+describe("TickTickReconnectSync (app-lifetime cache purge)", () => {
+ it("drops task caches and resets status on a WS reconnect (disconnected→connected)", async () => {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ // Warm caches under the PRIOR account — the tab survived a Core restart.
+ queryClient.setQueryData(["ticktick", "tasks", "acct-A"], {
+ tasks: [
+ {
+ id: "old",
+ title: "A's task",
+ kind: "TEXT",
+ priority: 0,
+ tags: [],
+ checklist_items: [],
+ },
+ ],
+ source_limit_reached: false,
+ });
+ queryClient.setQueryData(["ticktick", "status"], {
+ state: "connected",
+ connection_id: "acct-A",
+ });
+
+ render(, {
+ wrapper: wrapper({
+ // A real reconnect EDGE: a drop, then back to connected.
+ connectionStatus: Stream.make(
+ "reconnecting" as ConnectionStatus,
+ "connected" as ConnectionStatus,
+ ),
+ queryClient,
+ }),
+ });
+
+ // The reconnect drops every task query AND resets status, so the next
+ // status read mints the fresh id — account A can never render under B.
+ await waitFor(() =>
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-A"]),
+ ).toBeUndefined(),
+ );
+ await waitFor(() =>
+ expect(queryClient.getQueryData(["ticktick", "status"])).toBeUndefined(),
+ );
+ });
+
+ it("leaves a warm cache intact on a plain mount replay (no prior drop)", async () => {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+ queryClient.setQueryData(["ticktick", "tasks", "acct-A"], {
+ tasks: [
+ {
+ id: "warm",
+ title: "warm task",
+ kind: "TEXT",
+ priority: 0,
+ tags: [],
+ checklist_items: [],
+ },
+ ],
+ source_limit_reached: false,
+ });
+
+ // A test-driven stream (not a canned one): first the mount replay, then —
+ // only after asserting survival — a REAL reconnect edge. The eventual purge
+ // proves the SAME ordered fiber consumed the replay first, so the survival
+ // assertion is ordering-based, not a fixed sleep (CodeRabbit #336).
+ const queue = Effect.runSync(Queue.unbounded());
+ render(, {
+ wrapper: wrapper({
+ connectionStatus: Stream.fromQueue(queue),
+ queryClient,
+ }),
+ });
+
+ // Mount replay: a lone `connected` with NO prior non-connected state
+ // (ADR-0051 `.changes` replays current on subscribe).
+ await Effect.runPromise(
+ Queue.offer(queue, "connected" as ConnectionStatus),
+ );
+ // The replay is NOT a reconnect → the warm cache survives (review F2/F5).
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-A"]),
+ ).toBeDefined();
+
+ // Now a REAL edge through the same stream: the purge landing proves the
+ // observer processed the whole ordered sequence — replay included.
+ await Effect.runPromise(
+ Queue.offer(queue, "reconnecting" as ConnectionStatus),
+ );
+ await Effect.runPromise(
+ Queue.offer(queue, "connected" as ConnectionStatus),
+ );
+ await waitFor(() =>
+ expect(
+ queryClient.getQueryData(["ticktick", "tasks", "acct-A"]),
+ ).toBeUndefined(),
+ );
+ });
+});
+
+// Review #4: the initial-vs-stale split keys on `data === undefined`, not row
+// count. TanStack retains the last-good `data` through a failed refetch (a
+// successful fetch then a refetch failure lands `status: 'error'` with the prior
+// data still present) — so a valid EMPTY fetch (`{tasks: []}`) whose refetch
+// later fails is a STALE error over an empty cache, NEVER an initial one. The
+// old `rows.length === 0` could not tell that empty-but-valid cache from "no data
+// yet"; this classifier can.
+describe("classifyTasksError (initial vs stale)", () => {
+ it("classifies a failed refetch over a valid empty cache as stale, not initial", () => {
+ expect(
+ classifyTasksError(true, { tasks: [], source_limit_reached: false }),
+ ).toEqual({ tasksInitialError: false, tasksStaleError: true });
+ });
+
+ it("classifies a failure with no prior fetch as initial", () => {
+ expect(classifyTasksError(true, undefined)).toEqual({
+ tasksInitialError: true,
+ tasksStaleError: false,
+ });
+ });
+
+ it("reports neither flag when there is no error", () => {
+ expect(
+ classifyTasksError(false, { tasks: [], source_limit_reached: false }),
+ ).toEqual({ tasksInitialError: false, tasksStaleError: false });
+ expect(classifyTasksError(false, undefined)).toEqual({
+ tasksInitialError: false,
+ tasksStaleError: false,
+ });
+ });
+});
diff --git a/apps/web/test/store/bridge.test.tsx b/apps/web/test/store/bridge.test.tsx
index 9701a187..9ab76439 100644
--- a/apps/web/test/store/bridge.test.tsx
+++ b/apps/web/test/store/bridge.test.tsx
@@ -33,6 +33,7 @@ import {
} from "@/store/bridge.js";
import {
appendMessage,
+ applyEvent,
attachRun,
getChatState,
resetChatStore,
@@ -358,11 +359,18 @@ describe("decideProposal resume fiber tracking (M2)", () => {
});
describe("cancelRun (ADR-0014)", () => {
- /** A stub whose subscribeRun never terminates and whose cancelRun returns `outcome`. */
+ /** A stub whose subscribeRun never terminates and whose cancelRun returns
+ * `outcome` + `live_tail` (default false — no live stream event follows). */
function makeCancelRuntime(outcome: {
readonly outcome: "accepted" | "already_terminal" | "unknown_run";
+ readonly live_tail?: boolean;
}) {
- const cancelRun = vi.fn(() => Effect.succeed(outcome));
+ const cancelRun = vi.fn(() =>
+ Effect.succeed({
+ outcome: outcome.outcome,
+ live_tail: outcome.live_tail ?? false,
+ }),
+ );
const subscribeRun = vi.fn(
(_runId: RunId): Stream.Stream =>
Stream.fromQueue(Effect.runSync(Queue.unbounded())),
@@ -422,6 +430,95 @@ describe("cancelRun (ADR-0014)", () => {
await runtime.dispose();
});
+ it("on accepted for a RUNNING run: applies the real interrupted tool_call + cancelled tail (A4)", async () => {
+ // Core pins the wire order response → interrupted tool_call(s) →
+ // cancelled (external-task-views A4). The bridge must let the live stream
+ // APPLY them — a synthetic settle would drop the interrupted result and
+ // diverge live from reload.
+ const queue = Effect.runSync(Queue.unbounded());
+ const cancelRun = vi.fn(() =>
+ Effect.sync(() => {
+ // The event tail lands right behind the response, as Core does.
+ Queue.unsafeOffer(queue, {
+ kind: "tool_call",
+ tool_call_id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "error",
+ result: {
+ content: [{ type: "text", text: "interrupted" }],
+ is_error: true,
+ },
+ });
+ Queue.unsafeOffer(queue, { kind: "cancelled" });
+ // live_tail: true — the stream delivers the real interrupted +
+ // cancelled tail; the bridge must NOT synthesize its own.
+ return { outcome: "accepted" as const, live_tail: true };
+ }),
+ );
+ const subscribeRun = vi.fn(
+ (_runId: RunId): Stream.Stream =>
+ Stream.fromQueue(queue),
+ );
+ const runtime = makeCoreRuntime({ overrides: { subscribeRun, cancelRun } });
+ const runId = "run-cancel-external" as RunId;
+ seedActiveRun(runId, runtime);
+ // The external call is in flight (a running row from the started event).
+ applyEvent("t1", runId, {
+ kind: "tool_call",
+ tool_call_id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "started",
+ });
+
+ await cancelRunBridge(runtime, runId);
+ // The stream applies the tail and its takeUntil reaps the fiber.
+ await vi.waitFor(() => {
+ expect(hasRunFiber(runId)).toBe(false);
+ });
+
+ const thread = getChatState().threads.t1;
+ const message = thread?.messages.find((m) => m.id === "a1");
+ expect(message?.status).toBe("incomplete");
+ expect(message?.cancelled).toBe(true);
+ // The row settled from the REAL interrupted event: error + the
+ // Core-generated result — the same object reload will serve.
+ const row = message?.segments.find((s) => s.kind === "tool_call");
+ expect(row?.kind === "tool_call" && row.call).toEqual({
+ id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "error",
+ arg: undefined,
+ result: {
+ content: [{ type: "text", text: "interrupted" }],
+ is_error: true,
+ },
+ });
+
+ await runtime.dispose();
+ });
+
+ it("on accepted WITHOUT a live tail: settles immediately off the response (no timer)", async () => {
+ // live_tail: false is Core's explicit "no stream event will follow"
+ // (parked, or the running-without-hub resume window). The bridge settles
+ // synthetically at once — no 3-second grace timer, no wedged Stop.
+ const { runtime } = makeCancelRuntime({
+ outcome: "accepted",
+ live_tail: false,
+ });
+ const runId = "run-cancel-no-tail" as RunId;
+ seedActiveRun(runId, runtime);
+
+ await cancelRunBridge(runtime, runId);
+
+ const thread = getChatState().threads.t1;
+ expect(thread?.messages.find((m) => m.id === "a1")?.status).toBe(
+ "incomplete",
+ );
+ expect(hasRunFiber(runId)).toBe(false);
+
+ await runtime.dispose();
+ });
+
it("on already_terminal for a RUNNING run: leaves it untouched (the stream owns the final state)", async () => {
const { runtime, cancelRun } = makeCancelRuntime({
outcome: "already_terminal",
@@ -541,7 +638,8 @@ describe("cancelRun (ADR-0014)", () => {
const runtime = makeCoreRuntime({
overrides: {
subscribeRun,
- cancelRun: () => Effect.succeed({ outcome: "accepted" as const }),
+ cancelRun: () =>
+ Effect.succeed({ outcome: "accepted" as const, live_tail: false }),
retryRun: () => Effect.succeed({ outcome: "accepted" as const }),
proposalDecide: () =>
Effect.promise(() => decideGate).pipe(
diff --git a/apps/web/test/store/chat.test.tsx b/apps/web/test/store/chat.test.tsx
index f01638dd..063b6868 100644
--- a/apps/web/test/store/chat.test.tsx
+++ b/apps/web/test/store/chat.test.tsx
@@ -211,6 +211,51 @@ describe("chat store + stream bridge", () => {
await runtime.dispose();
});
+ it("merges a terminal event's result into the existing external call (A4)", async () => {
+ const queue = Effect.runSync(Queue.unbounded());
+ const runtime = makeStubRuntime(queue, "run-external");
+
+ await send(runtime, "threadA", "how many tasks tomorrow?");
+
+ Queue.unsafeOffer(queue, {
+ kind: "tool_call",
+ tool_call_id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "started",
+ });
+ Queue.unsafeOffer(queue, {
+ kind: "tool_call",
+ tool_call_id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "completed",
+ result: {
+ content: [{ type: "text", text: "1 task found: S1 timed" }],
+ is_error: false,
+ },
+ });
+ Queue.unsafeOffer(queue, { kind: "done" });
+ await awaitRun(runtime, "run-external");
+
+ const assistant = getChatState().threads.threadA?.messages[1];
+ expect(
+ (assistant?.segments ?? [])
+ .filter((s) => s.kind === "tool_call")
+ .map((s) => s.call),
+ ).toEqual([
+ {
+ id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "completed",
+ result: {
+ content: [{ type: "text", text: "1 task found: S1 timed" }],
+ is_error: false,
+ },
+ },
+ ]);
+
+ await runtime.dispose();
+ });
+
it("maps a tool_call error status onto the matching row", async () => {
const queue = Effect.runSync(Queue.unbounded());
const runtime = makeStubRuntime(queue, "run-tool-err");
@@ -550,6 +595,40 @@ describe("segment timeline (ADR-0045)", () => {
expect(concatText(segs)).toBe("First. Second. Done.");
});
+ it("a snapshot ending with an OPEN reasoning block seals it on the next boundary (F4)", () => {
+ seedRun("tF4", "run-f4");
+
+ // A reconnect `snapshot` whose LAST segment is an OPEN reasoning block (no
+ // `duration_ms`). The wire snapshot carries no open-time, so applyEvent must
+ // RE-ANCHOR `reasoningOpenedAt` to `now`; without it a later boundary can
+ // never seal the block and it stays "Thinking…" forever (review F4).
+ applyEvent(
+ "tF4",
+ "run-f4",
+ {
+ kind: "snapshot",
+ segments: [
+ { kind: "text", text: "hello" },
+ { kind: "reasoning", text: "thinking" },
+ ],
+ },
+ 1_000,
+ );
+ // Right after the snapshot the block is open (unsealed).
+ expect(segmentsOf("tF4", "run-f4")).toEqual([
+ { kind: "text", text: "hello" },
+ { kind: "reasoning", text: "thinking" },
+ ]);
+
+ // A later boundary seals it with a duration web-clocked from the snapshot instant.
+ applyEvent("tF4", "run-f4", { kind: "text_delta", delta: "world" }, 3_000);
+ expect(segmentsOf("tF4", "run-f4")).toEqual([
+ { kind: "text", text: "hello" },
+ { kind: "reasoning", text: "thinking", durationMs: 2_000 },
+ { kind: "text", text: "world" },
+ ]);
+ });
+
it("appends a proposal segment exactly once per run (skip-if-present)", () => {
seedRun("tDup", "run-dup");
const proposal = {
diff --git a/apps/web/test/store/hydrate.test.tsx b/apps/web/test/store/hydrate.test.tsx
index 45262db0..1ad6eafd 100644
--- a/apps/web/test/store/hydrate.test.tsx
+++ b/apps/web/test/store/hydrate.test.tsx
@@ -99,16 +99,31 @@ describe("refresh-durable hydration", () => {
segments: [
{
kind: "tool_call",
+ tool_call_id: "tc_1",
name: "search_entities",
status: "completed",
arg: "Lev",
},
{
kind: "tool_call",
+ tool_call_id: "tc_2",
name: "search_entities",
status: "error",
arg: "Acme",
},
+ // An external call reloads WITH its model-received result
+ // (external-task-views A4), so the row expands identically
+ // to the live one.
+ {
+ kind: "tool_call",
+ tool_call_id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "completed",
+ result: {
+ content: [{ type: "text", text: "1 task found" }],
+ is_error: false,
+ },
+ },
{ kind: "text", text: "done" },
],
},
@@ -127,23 +142,41 @@ describe("refresh-durable hydration", () => {
await hydrateThread(runtime, "tTools");
const assistant = getChatState().threads.tTools?.messages[1];
+ // The rows key on the DURABLE tool_call_id (external-task-views A4) — the
+ // same id the live `tool_call` Run Event carried, so the reload row keys
+ // identically to the live one.
expect(assistant?.segments.filter((s) => s.kind === "tool_call")).toEqual([
{
kind: "tool_call",
call: {
- id: "m2:seg:0",
+ id: "tc_1",
name: "search_entities",
status: "completed",
arg: "Lev",
+ result: undefined,
},
},
{
kind: "tool_call",
call: {
- id: "m2:seg:1",
+ id: "tc_2",
name: "search_entities",
status: "error",
arg: "Acme",
+ result: undefined,
+ },
+ },
+ {
+ kind: "tool_call",
+ call: {
+ id: "tc_ext",
+ name: "ticktick_filter_tasks",
+ status: "completed",
+ arg: undefined,
+ result: {
+ content: [{ type: "text", text: "1 task found" }],
+ is_error: false,
+ },
},
},
]);
diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml
index 1d74a7c6..03c91df7 100644
--- a/crates/core/Cargo.toml
+++ b/crates/core/Cargo.toml
@@ -2,11 +2,15 @@
name = "core"
version = "0.1.0"
edition = "2024"
+# let-chains (used across the crate) stabilized in 1.88; CI runs unpinned stable.
+rust-version = "1.88"
[dependencies]
anyhow = "1"
axum = { version = "0.8", features = ["ws"] }
base64 = "0.22"
+libc = "0.2"
+reqwest = { version = "0.12", features = ["json"] }
rust-embed = { version = "8", features = ["mime-guess"] }
schemars = "0.8"
serde = { version = "1", features = ["derive"] }
@@ -21,6 +25,7 @@ tower-http = { version = "0.6", features = ["fs"] }
tracing = "0.1"
tracing-appender = "0.2"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+url = "2"
uuid = { version = "1", features = ["v7", "serde"] }
[dev-dependencies]
diff --git a/crates/core/src/cancel.rs b/crates/core/src/cancel.rs
index dd145181..a8be8c62 100644
--- a/crates/core/src/cancel.rs
+++ b/crates/core/src/cancel.rs
@@ -1,121 +1,95 @@
//! Run cancellation as one deep, directly-testable verb (ADR-0029, extending the
//! `proposal/decide` → [`crate::decide`] precedent to `run/cancel`).
//!
-//! [`cancel`] owns the whole decision: read the Run status, pick the parked vs
-//! running guarded transition (ADR-0028), and on a won running-cancel perform the
-//! Worker signal. It returns a typed [`Outcome`] — `Accepted` / `AlreadyTerminal`
-//! / `UnknownRun` — the three [ADR-0014](../docs/adr/0014-client-core-wire-protocol.md)
-//! result values, NOT error codes. The only failure channel is a DB fault, which
-//! rides `anyhow::Error` (the handler maps it to `-32603`); the negative-but-
-//! expected domain outcomes stay in the `Ok` payload (ADR-0029 "protocol error vs
-//! result value").
+//! [`cancel`] owns the whole decision AND its side effects: read the Run status,
+//! pick the parked vs running guarded transition (ADR-0028), and — for a won
+//! running-cancel with a live hub — signal the Worker, frame the Response (via
+//! the injected `respond`), settle + publish the interrupted external calls, and
+//! publish the terminal `Cancelled`, ALL under ONE lifecycle-slot + hub-gate
+//! acquisition. Holding both across the settle tx AND the raw event sends makes
+//! generation changes and `run/subscribe` classification atomic with the whole
+//! sequence.
//!
-//! The hub interaction is INJECTED as a closure (`get_hub`) so the decision + the
-//! Worker signal are assertable against a `:memory:` pool without the live `Hubs`
-//! registry — mirroring how [`crate::decide::apply`] injects `worker::resume`
-//! (ADR-0026: the verb takes no new subsystem dependency). On a won running-cancel
-//! the verb signals the live Worker and returns the won [`RunHub`] inside
-//! [`Outcome::Accepted`]; the terminal `Cancelled` publish + `hub::remove` are
-//! performed by [`publish_cancelled`], which the thin handler calls AFTER framing
-//! its Response — preserving the deterministic `response → cancelled` wire order.
+//! Response framing is INJECTED as `respond` so the verb frames it in the right
+//! place (inside the gate, BEFORE the events — pinning the wire order
+//! response → interrupted → cancelled) while staying assertable against a
+//! `:memory:` pool. The only failure channel is a DB fault on `anyhow::Error`
+//! (the handler maps it to `-32603`); expected domain outcomes ride the `respond`
+//! string (`accepted` / `already_terminal` / `unknown_run`), ADR-0029.
use sqlx::SqlitePool;
use uuid::Uuid;
use crate::db::{self, RunStatus};
-use crate::hub::{self, Hubs, RunHub};
+use crate::hub::{self, Hubs};
use crate::protocol::RunEvent;
-/// The result of a cancel request (ADR-0014 result values, not error codes). The
-/// handler maps each to its wire `outcome` string.
-pub enum Outcome {
- /// The Run was live (running) or parked and is now cancelling. For a won
- /// running-cancel this carries the live [`RunHub`] the verb signalled, so the
- /// handler can publish the terminal `Cancelled` AFTER framing its Response; a
- /// parked cancel carries `None` (no live Worker to signal or publish for).
- Accepted { hub: Option },
- /// The Run had already finished (terminal) or a concurrent winner committed the
- /// terminal transition first — nothing to cancel.
- AlreadyTerminal,
- /// No Run with this id.
- UnknownRun,
-}
-
-/// Cancel a Run (ADR-0014, ADR-0028). Reads the status, picks the guarded
-/// transition, and on a won running-cancel signals the live Worker via the
-/// injected `get_hub`. Returns the typed [`Outcome`]; a DB fault is the only
-/// `Err`.
-///
-/// `get_hub` resolves the live [`RunHub`] for a run id (production: `|id|
-/// hub::get(hubs, id)`); injected so the decision + Worker signal are testable
-/// against `:memory:` without the live registry.
-pub async fn cancel(pool: &SqlitePool, run_id: Uuid, get_hub: F) -> anyhow::Result
-where
- F: FnOnce(Uuid) -> Option,
-{
+/// Cancel a Run (ADR-0014/0028/0029). The transient lifecycle slot makes
+/// the durable status, active hub generation, and any terminal drain one
+/// linearized decision. `respond(outcome, live_tail)` is framed before live
+/// terminal events so the initiating connection observes response first.
+pub async fn cancel(
+ pool: &SqlitePool,
+ hubs: &Hubs,
+ run_id: Uuid,
+ respond: impl FnOnce(&str, bool),
+) -> anyhow::Result<()> {
+ let lifecycle = hub::lifecycle(hubs, run_id).await;
match db::run_status(pool, run_id).await? {
- // Unknown run id — an ADR-0014 result value, not an error code.
- None => Ok(Outcome::UnknownRun),
+ None => respond("unknown_run", false),
Some(RunStatus::Parked) => {
- // Parked Run has no live Worker: a pure tier-2 flip of the Run + its
- // pending Proposal. A rollback (no pending Proposal, or a concurrent
- // decide/cancel already won) maps to AlreadyTerminal.
- if db::cancel_parked_run(pool, run_id, db::now_ms()).await? {
- Ok(Outcome::Accepted { hub: None })
- } else {
- Ok(Outcome::AlreadyTerminal)
- }
+ let accepted = db::cancel_parked_run(pool, run_id, db::now_ms()).await?;
+ respond(
+ if accepted {
+ "accepted"
+ } else {
+ "already_terminal"
+ },
+ false,
+ );
}
- Some(RunStatus::Running) => {
- // Win the guarded running -> cancelled transition first; the DB
- // transition is the user-visible outcome. On a win, signal the live
- // Worker (cleanup) and hand the hub back so the handler publishes the
- // terminal Cancelled AFTER framing its Response.
- if db::cancel_running_run(pool, run_id, db::now_ms()).await?.won() {
- let hub = get_hub(run_id);
- if let Some(run_hub) = &hub {
- run_hub.cancel();
+ Some(RunStatus::Running) => match hub::get(hubs, run_id) {
+ Some(run_hub) => {
+ let gate = run_hub.gate().await;
+ match db::cancel_running_run(pool, run_id, db::now_ms()).await? {
+ db::Terminal::Won { interrupted } => {
+ run_hub.cancel();
+ respond("accepted", true);
+ crate::worker::publish_interrupted(&run_hub, interrupted);
+ run_hub.send(RunEvent::Cancelled);
+ hub::remove_own(hubs, run_id, &run_hub, &lifecycle);
+ }
+ db::Terminal::Lost => respond("already_terminal", false),
}
- Ok(Outcome::Accepted { hub })
- } else {
- // The Worker committed a terminal transition first.
- Ok(Outcome::AlreadyTerminal)
+ drop(gate);
}
- }
- // Completed, errored, or cancelled — the Run already ended. The terminal set
- // is classified once by `is_terminal` (ADR-0028), not re-spelled here.
- Some(status) if status.is_terminal() => Ok(Outcome::AlreadyTerminal),
- // Unreachable: the two live states are matched above and the rest are
- // terminal. A guarded arm does not count toward match exhaustiveness, so
- // this explicit arm is required.
- Some(_) => Ok(Outcome::AlreadyTerminal),
+ None => {
+ let terminal = db::cancel_running_run(pool, run_id, db::now_ms()).await?;
+ respond(
+ if terminal.won() {
+ "accepted"
+ } else {
+ "already_terminal"
+ },
+ false,
+ );
+ }
+ },
+ Some(_) => respond("already_terminal", false),
}
-}
-
-/// Publish the terminal `Cancelled` Run Event and remove the hub, after a won
-/// running-cancel. Called by the handler AFTER it frames the cancel Response, so
-/// the client always sees `response → cancelled` (not a racing broadcast). The
-/// gated publish (`lock → send → unlock`, ADR-0022) is
-/// [`RunHub::publish_gated`]; then `hub::remove`.
-pub async fn publish_cancelled(hubs: &Hubs, run_id: Uuid, hub: Option) {
- let Some(run_hub) = hub else {
- return;
- };
-
- run_hub.publish_gated(RunEvent::Cancelled).await;
-
- hub::remove(hubs, run_id);
+ Ok(())
}
#[cfg(test)]
mod tests {
- use crate::db::test_support::memory_pool;
- use super::{cancel, publish_cancelled, Outcome};
+ use super::cancel;
use crate::db;
+ use crate::db::test_support::memory_pool;
use crate::hub;
- use crate::protocol::RunEvent;
+ use crate::protocol::{RunEvent, ToolCallStatus, TranscriptToolResult};
use crate::workflow::Workflow;
use sqlx::SqlitePool;
+ use std::cell::Cell;
use uuid::Uuid;
fn test_workflow() -> Workflow {
@@ -127,6 +101,7 @@ mod tests {
system_prompt: "sp".to_string(),
thinking_level: Some("off".to_string()),
tools: vec!["propose_workspace_mutation".to_string()],
+ external_tools: false,
}
}
@@ -191,25 +166,41 @@ mod tests {
.expect("count pending proposals")
}
- // 1. Parked Run → Accepted (no hub); the Run AND its pending Proposal flip to
- // cancelled. The verb takes the pure tier-2 parked path; no Worker to signal.
+ /// Run `cancel`, recording the single `respond(outcome, live_tail)` call.
+ async fn cancel_recording(pool: &SqlitePool, hubs: &hub::Hubs, run_id: Uuid) -> (String, bool) {
+ let recorded: Cell> = Cell::new(None);
+ cancel(pool, hubs, run_id, |outcome, live_tail| {
+ recorded.set(Some((outcome.to_string(), live_tail)));
+ })
+ .await
+ .expect("cancel ok");
+ recorded
+ .into_inner()
+ .expect("respond was called exactly once")
+ }
+
+ // 1. Parked Run → accepted (no live tail); the Run AND its pending Proposal
+ // flip to cancelled. Pure tier-2 parked path; no Worker to signal.
#[tokio::test]
async fn parked_run_is_accepted_and_flips_run_and_proposal() {
let pool = memory_pool().await;
let run_id = seed_parked_run(&pool).await;
- assert_eq!(pending_proposal_count(&pool, run_id).await, 1, "seed: one pending proposal");
+ assert_eq!(
+ pending_proposal_count(&pool, run_id).await,
+ 1,
+ "seed: one pending proposal"
+ );
- // get_hub must NOT be consulted on the parked path — a parked Run has no
- // live Worker. Panic if it is, to pin the parked branch.
- let outcome = cancel(&pool, run_id, |_| panic!("parked path must not touch the hub"))
- .await
- .expect("cancel ok");
+ let hubs = hub::new_hubs();
+ let (outcome, live_tail) = cancel_recording(&pool, &hubs, run_id).await;
- assert!(
- matches!(outcome, Outcome::Accepted { hub: None }),
- "a parked cancel is Accepted with no hub"
+ assert_eq!(outcome, "accepted");
+ assert!(!live_tail, "a parked cancel has no live tail");
+ assert_eq!(
+ run_status_str(&pool, run_id).await,
+ Some("cancelled"),
+ "run cancelled"
);
- assert_eq!(run_status_str(&pool, run_id).await, Some("cancelled"), "run cancelled");
assert_eq!(
pending_proposal_count(&pool, run_id).await,
0,
@@ -217,102 +208,140 @@ mod tests {
);
}
- // 2. Running Run, cancel WINS → Accepted carrying the live hub; the verb
- // signalled the Worker (is_cancelled), and publish_cancelled then broadcasts
- // Cancelled + removes the hub.
+ // 2. Running Run, cancel WINS → accepted with a live tail; the verb signals
+ // the Worker (is_cancelled), publishes the terminal Cancelled, and removes
+ // the hub — ALL inside one gated section (review P1 #3).
#[tokio::test]
- async fn running_won_signals_then_publishes_and_removes() {
+ async fn running_won_signals_publishes_and_removes_under_the_gate() {
let pool = memory_pool().await;
let run_id = seed_running_run(&pool).await;
- // A real registered hub + a tail subscriber to observe the published event.
let hubs = hub::new_hubs();
- let registered = hub::create(&hubs, run_id);
+ let registered = hub::register(&hubs, run_id).expect("fresh run registers");
let mut tail = registered.subscribe_raw();
- let outcome = cancel(&pool, run_id, |id| hub::get(&hubs, id))
- .await
- .expect("cancel ok");
-
- let hub = match outcome {
- Outcome::Accepted { hub: Some(hub) } => hub,
- _ => panic!("a won running-cancel is Accepted with the live hub"),
- };
- assert_eq!(run_status_str(&pool, run_id).await, Some("cancelled"), "run cancelled");
- assert!(hub.is_cancelled(), "the verb signalled the live Worker");
- // No terminal event published yet — that's publish_cancelled's job, AFTER
- // the handler frames its Response.
- assert!(tail.try_recv().is_err(), "verb itself publishes no event");
-
- publish_cancelled(&hubs, run_id, Some(hub)).await;
+ let (outcome, live_tail) = cancel_recording(&pool, &hubs, run_id).await;
+ assert_eq!(outcome, "accepted");
+ assert!(live_tail, "a won running-cancel carries a live tail");
+ assert_eq!(
+ run_status_str(&pool, run_id).await,
+ Some("cancelled"),
+ "run cancelled"
+ );
+ assert!(
+ registered.is_cancelled(),
+ "the verb signalled the live Worker"
+ );
+ // The terminal Cancelled was published under the gate (no separate step),
+ // and the hub was removed.
assert!(
matches!(tail.try_recv(), Ok(RunEvent::Cancelled)),
- "publish_cancelled broadcasts the terminal Cancelled"
+ "the gated section broadcasts the terminal Cancelled"
+ );
+ assert!(
+ hub::get(&hubs, run_id).is_none(),
+ "the hub is removed after publish"
);
- assert!(hub::get(&hubs, run_id).is_none(), "the hub is removed after publish");
}
- // 3. Running Run, but a terminal transition already committed → cancel LOSES the
- // guard → AlreadyTerminal; no signal, no publish.
+ // 2b. Cancel-after-started (external-task-views A4): a running Run with a
+ // PENDING external call settles it as interrupted inside the SAME gated
+ // section, publishing interrupted `tool_call` → `Cancelled` in order.
#[tokio::test]
- async fn running_lost_to_committed_terminal_is_already_terminal() {
+ async fn cancel_after_external_started_publishes_interrupted_then_cancelled() {
let pool = memory_pool().await;
let run_id = seed_running_run(&pool).await;
- // The Worker reached `done` first: commit the running -> completed move.
- assert!(
- db::complete_run(&pool, run_id, db::now_ms()).await.expect("complete").won(),
- "seed: the run completes before the cancel"
- );
+ // The Worker reported an external call started; no finished frame yet.
+ db::persist_tool_call(
+ &pool,
+ run_id,
+ "tc-ext",
+ "ticktick_filter_tasks",
+ r#"{"filter":{"status":[0]}}"#,
+ db::now_ms(),
+ )
+ .await
+ .expect("persist pending external call");
- let outcome = cancel(&pool, run_id, |_| panic!("a lost running-cancel must not touch the hub"))
- .await
- .expect("cancel ok");
+ let hubs = hub::new_hubs();
+ let registered = hub::register(&hubs, run_id).expect("fresh run registers");
+ let mut tail = registered.subscribe_raw();
- assert!(
- matches!(outcome, Outcome::AlreadyTerminal),
- "a running-cancel that lost the guard is AlreadyTerminal"
- );
+ let (outcome, _live_tail) = cancel_recording(&pool, &hubs, run_id).await;
+ assert_eq!(outcome, "accepted");
+
+ // The row settled in the cancel transition, as an error carrying the
+ // Core-generated interrupted result.
+ let (status, payload): (String, Option) =
+ sqlx::query_as("SELECT status, result_payload FROM tool_calls WHERE id = 'tc-ext'")
+ .fetch_one(&pool)
+ .await
+ .expect("read settled row");
+ assert_eq!(status, "errored");
assert_eq!(
- run_status_str(&pool, run_id).await,
- Some("completed"),
- "the committed completion stands"
+ serde_json::from_str::(&payload.unwrap()).unwrap(),
+ TranscriptToolResult::interrupted()
);
+
+ // Pinned order (all published under the one gate): interrupted tool_call
+ // event(s) BEFORE the terminal Cancelled.
+ let mut events = Vec::new();
+ while let Ok(event) = tail.try_recv() {
+ events.push(event);
+ }
+ match events.as_slice() {
+ [
+ RunEvent::ToolCall {
+ tool_call_id,
+ status: ToolCallStatus::Error,
+ result: Some(result),
+ ..
+ },
+ RunEvent::Cancelled,
+ ] => {
+ assert_eq!(tool_call_id, "tc-ext");
+ assert_eq!(*result, TranscriptToolResult::interrupted());
+ }
+ other => panic!("expected [interrupted tool_call, Cancelled], got {other:?}"),
+ }
}
- // 4. A Run that already ended (terminal) → AlreadyTerminal, classified by
- // is_terminal without re-reading the running/parked guards.
+ // 3. A Run that already ended (terminal) → already_terminal, classified by
+ // is_terminal without touching the hub.
#[tokio::test]
async fn terminal_run_is_already_terminal() {
let pool = memory_pool().await;
let run_id = seed_running_run(&pool).await;
- assert!(db::complete_run(&pool, run_id, db::now_ms()).await.expect("complete").won());
+ assert!(
+ db::complete_run(&pool, run_id, db::now_ms())
+ .await
+ .expect("complete")
+ .won()
+ );
- let outcome = cancel(&pool, run_id, |_| panic!("a terminal Run must not touch the hub"))
- .await
- .expect("cancel ok");
+ let hubs = hub::new_hubs();
+ let (outcome, live_tail) = cancel_recording(&pool, &hubs, run_id).await;
- assert!(
- matches!(outcome, Outcome::AlreadyTerminal),
- "cancelling an already-completed Run is AlreadyTerminal"
+ assert_eq!(
+ outcome, "already_terminal",
+ "cancelling a completed Run is already_terminal"
);
+ assert!(!live_tail);
}
- // 5. An id with no Run row → UnknownRun.
+ // 4. An id with no Run row → unknown_run.
#[tokio::test]
async fn unknown_run_is_unknown_run() {
let pool = memory_pool().await;
- let outcome = cancel(&pool, Uuid::now_v7(), |_| panic!("unknown Run must not touch the hub"))
- .await
- .expect("cancel ok");
- assert!(
- matches!(outcome, Outcome::UnknownRun),
- "an unknown run id is UnknownRun"
- );
+ let hubs = hub::new_hubs();
+ let (outcome, live_tail) = cancel_recording(&pool, &hubs, Uuid::now_v7()).await;
+ assert_eq!(outcome, "unknown_run");
+ assert!(!live_tail);
}
- // 6. Parked Run whose pending Proposal already vanished (a concurrent decide won)
- // → the guarded parked transition rolls back → AlreadyTerminal.
+ // 5. Parked Run whose pending Proposal already vanished (a concurrent decide
+ // won) → the guarded parked transition rolls back → already_terminal.
#[tokio::test]
async fn parked_race_lost_is_already_terminal() {
let pool = memory_pool().await;
@@ -328,15 +357,18 @@ mod tests {
.await
.expect("force proposal accepted");
- let outcome = cancel(&pool, run_id, |_| panic!("a lost parked race must not touch the hub"))
- .await
- .expect("cancel ok");
+ let hubs = hub::new_hubs();
+ let (outcome, _live_tail) = cancel_recording(&pool, &hubs, run_id).await;
- assert!(
- matches!(outcome, Outcome::AlreadyTerminal),
- "a parked cancel that lost the proposal race is AlreadyTerminal"
+ assert_eq!(
+ outcome, "already_terminal",
+ "a lost parked race is already_terminal"
);
// The Run stays parked (the transition rolled back) — the live decide owns it.
- assert_eq!(run_status_str(&pool, run_id).await, Some("parked"), "run stays parked");
+ assert_eq!(
+ run_status_str(&pool, run_id).await,
+ Some("parked"),
+ "run stays parked"
+ );
}
}
diff --git a/crates/core/src/config.rs b/crates/core/src/config.rs
index ed9be11d..8354ba0c 100644
--- a/crates/core/src/config.rs
+++ b/crates/core/src/config.rs
@@ -12,6 +12,11 @@ use std::time::Duration;
/// The default one-shot collector timeout (titler + probe): 15 seconds.
const DEFAULT_TIMEOUT_MS: u64 = 15_000;
+/// A7's per-request bound for the TickTick OpenAPI lane (review R12 #6): its
+/// own default (30s — a remote SaaS read, slower than local provider probes),
+/// overridable via `INKSTONE_TICKTICK_TIMEOUT_MS` like every other timeout.
+const TICKTICK_TIMEOUT_DEFAULT_MS: u64 = 30_000;
+
/// Boot-resolved configuration. Each field corresponds to one `INKSTONE_*` env
/// var; `None` means "unset, use the runtime default" (e.g. derive from the OS
/// data dir).
@@ -27,11 +32,20 @@ pub struct Config {
pub log_dir_override: Option,
pub title_timeout: Duration,
pub provider_test_timeout: Duration,
+ /// Per-request bound for TickTick OpenAPI reads (A7, review R12 #6).
+ pub ticktick_timeout: Duration,
pub worker_pre_spawn_delay: Option,
pub worker_log_path: Option,
/// The one browser origin allowed to open `/ws` remotely (ADR-0007).
/// Empty is unset; unset keeps remote browser origins closed.
pub public_origin: Option,
+ /// Test-only override of the TickTick MCP endpoint (external-task-views
+ /// A7): production uses the compile-time const. Empty is unset.
+ pub ticktick_mcp_url_override: Option,
+ /// Test-only override of the TickTick OpenAPI base URL (external-task-views
+ /// A7): the fake-HTTP-server harness points the Web lane at a local
+ /// fixture. Production uses the compile-time const. Empty is unset.
+ pub ticktick_api_url_override: Option,
}
impl Default for Config {
@@ -63,8 +77,15 @@ impl Config {
.map(PathBuf::from),
workflows_dir_override: get("INKSTONE_WORKFLOWS_DIR").map(PathBuf::from),
log_dir_override: get("INKSTONE_LOG_DIR").map(PathBuf::from),
- title_timeout: parse_timeout_ms(&get("INKSTONE_TITLE_TIMEOUT_MS")),
- provider_test_timeout: parse_timeout_ms(&get("INKSTONE_PROVIDER_TEST_TIMEOUT_MS")),
+ title_timeout: parse_timeout_ms(&get("INKSTONE_TITLE_TIMEOUT_MS"), DEFAULT_TIMEOUT_MS),
+ provider_test_timeout: parse_timeout_ms(
+ &get("INKSTONE_PROVIDER_TEST_TIMEOUT_MS"),
+ DEFAULT_TIMEOUT_MS,
+ ),
+ ticktick_timeout: parse_timeout_ms(
+ &get("INKSTONE_TICKTICK_TIMEOUT_MS"),
+ TICKTICK_TIMEOUT_DEFAULT_MS,
+ ),
worker_pre_spawn_delay: get("INKSTONE_WORKER_PRE_SPAWN_DELAY_MS")
.and_then(|v| v.to_str().and_then(|s| s.parse::().ok()))
.filter(|ms| *ms > 0)
@@ -73,20 +94,26 @@ impl Config {
public_origin: get("INKSTONE_PUBLIC_ORIGIN")
.and_then(|value| value.into_string().ok())
.filter(|value| !value.is_empty()),
+ ticktick_mcp_url_override: get("INKSTONE_TICKTICK_MCP_URL")
+ .and_then(|value| value.into_string().ok())
+ .filter(|value| !value.is_empty()),
+ ticktick_api_url_override: get("INKSTONE_TICKTICK_API_URL")
+ .and_then(|value| value.into_string().ok())
+ .filter(|value| !value.is_empty()),
}
}
}
-/// Parse a timeout env var: unset, unparseable, or `0` falls back to 15s.
+/// Parse a timeout env var: unset, unparseable, or `0` falls back to `default_ms`.
/// `0` is rejected because a zero-length timeout fires instantly, turning every
/// one-shot into a silent no-op.
-fn parse_timeout_ms(raw: &Option) -> Duration {
+fn parse_timeout_ms(raw: &Option, default_ms: u64) -> Duration {
let ms = raw
.as_ref()
.and_then(|v| v.to_str())
.and_then(|s| s.parse::().ok())
.filter(|ms| *ms > 0)
- .unwrap_or(DEFAULT_TIMEOUT_MS);
+ .unwrap_or(default_ms);
Duration::from_millis(ms)
}
@@ -182,9 +209,12 @@ mod tests {
env.insert("INKSTONE_LOG_DIR", "/tmp/logs");
env.insert("INKSTONE_TITLE_TIMEOUT_MS", "5000");
env.insert("INKSTONE_PROVIDER_TEST_TIMEOUT_MS", "3000");
+ env.insert("INKSTONE_TICKTICK_TIMEOUT_MS", "250");
env.insert("INKSTONE_WORKER_PRE_SPAWN_DELAY_MS", "100");
env.insert("INKSTONE_WORKER_LOG_PATH", "/tmp/worker.jsonl");
env.insert("INKSTONE_PUBLIC_ORIGIN", "https://inkstone.example.com");
+ env.insert("INKSTONE_TICKTICK_MCP_URL", "http://127.0.0.1:9/mcp");
+ env.insert("INKSTONE_TICKTICK_API_URL", "http://127.0.0.1:9");
let cfg = Config::from_lookup(lookup(&env));
@@ -202,6 +232,7 @@ mod tests {
assert_eq!(cfg.log_dir_override, Some(PathBuf::from("/tmp/logs")));
assert_eq!(cfg.title_timeout, Duration::from_millis(5000));
assert_eq!(cfg.provider_test_timeout, Duration::from_millis(3000));
+ assert_eq!(cfg.ticktick_timeout, Duration::from_millis(250));
assert_eq!(cfg.worker_pre_spawn_delay, Some(Duration::from_millis(100)));
assert_eq!(
cfg.worker_log_path,
@@ -211,6 +242,14 @@ mod tests {
cfg.public_origin.as_deref(),
Some("https://inkstone.example.com")
);
+ assert_eq!(
+ cfg.ticktick_mcp_url_override.as_deref(),
+ Some("http://127.0.0.1:9/mcp")
+ );
+ assert_eq!(
+ cfg.ticktick_api_url_override.as_deref(),
+ Some("http://127.0.0.1:9")
+ );
}
#[test]
@@ -226,9 +265,12 @@ mod tests {
assert_eq!(cfg.log_dir_override, None);
assert_eq!(cfg.title_timeout, Duration::from_millis(15_000));
assert_eq!(cfg.provider_test_timeout, Duration::from_millis(15_000));
+ assert_eq!(cfg.ticktick_timeout, Duration::from_millis(30_000));
assert_eq!(cfg.worker_pre_spawn_delay, None);
assert_eq!(cfg.worker_log_path, None);
assert_eq!(cfg.public_origin, None);
+ assert_eq!(cfg.ticktick_mcp_url_override, None);
+ assert_eq!(cfg.ticktick_api_url_override, None);
}
#[test]
@@ -250,11 +292,13 @@ mod tests {
let mut env = HashMap::new();
env.insert("INKSTONE_TITLE_TIMEOUT_MS", "0");
env.insert("INKSTONE_PROVIDER_TEST_TIMEOUT_MS", "0");
+ env.insert("INKSTONE_TICKTICK_TIMEOUT_MS", "0");
let cfg = Config::from_lookup(lookup(&env));
assert_eq!(cfg.title_timeout, Duration::from_millis(15_000));
assert_eq!(cfg.provider_test_timeout, Duration::from_millis(15_000));
+ assert_eq!(cfg.ticktick_timeout, Duration::from_millis(30_000));
}
#[test]
@@ -262,11 +306,13 @@ mod tests {
let mut env = HashMap::new();
env.insert("INKSTONE_TITLE_TIMEOUT_MS", "not-a-number");
env.insert("INKSTONE_PROVIDER_TEST_TIMEOUT_MS", "abc");
+ env.insert("INKSTONE_TICKTICK_TIMEOUT_MS", "invalid");
let cfg = Config::from_lookup(lookup(&env));
assert_eq!(cfg.title_timeout, Duration::from_millis(15_000));
assert_eq!(cfg.provider_test_timeout, Duration::from_millis(15_000));
+ assert_eq!(cfg.ticktick_timeout, Duration::from_millis(30_000));
}
#[test]
diff --git a/crates/core/src/credentials.rs b/crates/core/src/credentials.rs
index b1154cbb..bf7d9b7f 100644
--- a/crates/core/src/credentials.rs
+++ b/crates/core/src/credentials.rs
@@ -87,7 +87,7 @@ fn credentials_dir() -> Result {
Ok(parent.join("credentials"))
}
-fn credential_path(provider: &str) -> Result {
+pub(crate) fn credential_path(provider: &str) -> Result {
// Defense-in-depth: `provider` becomes a filename, so a value containing a
// path separator or `..` could escape the credentials dir. Handlers gate
// against the known-provider allowlist, but reject traversal here too so no
diff --git a/crates/core/src/db/lifecycle.rs b/crates/core/src/db/lifecycle.rs
index 8e98ad48..1ac3e30a 100644
--- a/crates/core/src/db/lifecycle.rs
+++ b/crates/core/src/db/lifecycle.rs
@@ -25,6 +25,54 @@ impl Moved {
}
}
+/// An external (`ticktick_*`) call a terminal transition settled as
+/// interrupted (external-task-views A4): the Run died between the call's
+/// started and finished frames. The caller publishes a
+/// `tool_call {status: error, result: interrupted}` event per entry after the
+/// transaction commits, before the terminal Run Event.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct InterruptedExternalCall {
+ pub tool_call_id: String,
+ pub name: String,
+}
+
+/// A terminal transition's outcome. `Won` carries the external calls its settle
+/// interrupted; `Lost` means a concurrent terminal transition already claimed the
+/// Run. A lost move never has interrupted rows — the enum makes that
+/// unrepresentable (was a struct whose "empty on a lost move" invariant lived in
+/// prose).
+#[derive(Debug)]
+pub enum Terminal {
+ Won {
+ interrupted: Vec,
+ },
+ Lost,
+}
+
+impl Terminal {
+ pub fn won(&self) -> bool {
+ matches!(self, Terminal::Won { .. })
+ }
+}
+
+/// Settle the Run's still-pending external calls inside a won terminal
+/// transition (external-task-views A4) — every terminal verb calls this, so
+/// cancel, worker error, EOF, AND the boot recovery sweep share one rule.
+async fn settle_interrupted_external_calls(
+ conn: &mut SqliteConnection,
+ run_id: Uuid,
+ now_ms: i64,
+) -> sqlx::Result> {
+ let payload = serde_json::to_string(&crate::protocol::TranscriptToolResult::interrupted())
+ .expect("TranscriptToolResult serializes");
+ let rows =
+ queries::settle_pending_external_tool_calls(&mut *conn, run_id, &payload, now_ms).await?;
+ Ok(rows
+ .into_iter()
+ .map(|(tool_call_id, name)| InterruptedExternalCall { tool_call_id, name })
+ .collect())
+}
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TerminalReason {
Completed,
@@ -85,17 +133,6 @@ impl RunStatus {
}
}
- /// Whether the Run has ended. The terminal grouping lives here once, so a
- /// read site asks the type instead of re-spelling the
- /// `completed | errored | cancelled` set. `running`/`parked` are non-terminal
- /// (a `parked` Run resumes; see CONTEXT.md *Run status*).
- pub fn is_terminal(self) -> bool {
- match self {
- Self::Completed | Self::Errored | Self::Cancelled => true,
- Self::Running | Self::Parked => false,
- }
- }
-
/// Whether the Run is parked, waiting on a Decision (ADR-0025). The parked
/// classifier lives here once for the resume-gate and subscribe read sites.
pub fn is_parked(self) -> bool {
@@ -106,7 +143,7 @@ impl RunStatus {
conn: &mut SqliteConnection,
run_id: Uuid,
now_ms: i64,
- ) -> sqlx::Result {
+ ) -> sqlx::Result {
debug_assert_eq!(Self::Running.as_str(), "running");
debug_assert_eq!(Self::Completed.as_str(), "completed");
let moved = Moved::from_rows(
@@ -119,12 +156,13 @@ impl RunStatus {
.await?,
);
if !moved.won() {
- return Ok(moved);
+ return Ok(Terminal::Lost);
}
queries::mark_assistant_messages_completed(&mut *conn, run_id, now_ms).await?;
run_log::append(&mut *conn, run_id, RunLogKind::Done, None, now_ms).await?;
- Ok(moved)
+ let interrupted = settle_interrupted_external_calls(&mut *conn, run_id, now_ms).await?;
+ Ok(Terminal::Won { interrupted })
}
pub(super) async fn fail(
@@ -134,7 +172,7 @@ impl RunStatus {
error_code: &str,
error_message: &str,
now_ms: i64,
- ) -> sqlx::Result {
+ ) -> sqlx::Result {
debug_assert_eq!(Self::Running.as_str(), "running");
debug_assert_eq!(Self::Errored.as_str(), "errored");
let moved = Moved::from_rows(
@@ -149,14 +187,15 @@ impl RunStatus {
.await?,
);
if !moved.won() {
- return Ok(moved);
+ return Ok(Terminal::Lost);
}
queries::mark_streaming_messages_incomplete(&mut *conn, run_id, now_ms).await?;
let payload =
serde_json::json!({ "code": error_code, "message": error_message }).to_string();
run_log::append(&mut *conn, run_id, RunLogKind::Error, Some(&payload), now_ms).await?;
- Ok(moved)
+ let interrupted = settle_interrupted_external_calls(&mut *conn, run_id, now_ms).await?;
+ Ok(Terminal::Won { interrupted })
}
pub(super) async fn park(
@@ -194,8 +233,8 @@ impl RunStatus {
/// `resume` guards `parked` and would match 0 rows here. On `won()` the terminal
/// fields are cleared back to live by the guarded query, and the retry milestone
/// reuses [`RunLogKind::Running`] — the same "now running" moment a fresh start
- /// logs (no new kind, no `run_log` CHECK change). `is_terminal()` and the boot
- /// sweep are unchanged; this is the single user-initiated exception.
+ /// logs (no new kind, no `run_log` CHECK change). The boot sweep is
+ /// unchanged; this is the single user-initiated exception.
pub(super) async fn retry(
conn: &mut SqliteConnection,
run_id: Uuid,
@@ -234,6 +273,10 @@ impl RunStatus {
}
queries::mark_streaming_messages_incomplete(&mut *conn, run_id, now_ms).await?;
+ // Settle still-pending external rows in this transition too — the one
+ // rule EVERY terminal verb shares. A parked Run has no live tail, so the
+ // settled rows surface on reload/late-subscribe, not as events.
+ settle_interrupted_external_calls(&mut *conn, run_id, now_ms).await?;
let payload = serde_json::json!({ "target": "run" }).to_string();
run_log::append(&mut *conn, run_id, RunLogKind::Cancelled, Some(&payload), now_ms).await?;
Ok(moved)
@@ -243,7 +286,7 @@ impl RunStatus {
conn: &mut SqliteConnection,
run_id: Uuid,
now_ms: i64,
- ) -> sqlx::Result {
+ ) -> sqlx::Result {
debug_assert_eq!(Self::Running.as_str(), "running");
debug_assert_eq!(Self::Cancelled.as_str(), "cancelled");
let moved = Moved::from_rows(
@@ -256,13 +299,14 @@ impl RunStatus {
.await?,
);
if !moved.won() {
- return Ok(moved);
+ return Ok(Terminal::Lost);
}
queries::mark_streaming_messages_incomplete(&mut *conn, run_id, now_ms).await?;
let payload = serde_json::json!({ "target": "run" }).to_string();
run_log::append(&mut *conn, run_id, RunLogKind::Cancelled, Some(&payload), now_ms).await?;
- Ok(moved)
+ let interrupted = settle_interrupted_external_calls(&mut *conn, run_id, now_ms).await?;
+ Ok(Terminal::Won { interrupted })
}
}
@@ -432,14 +476,6 @@ mod tests {
assert_eq!(RunStatus::from_str("bogus"), None);
assert_eq!(RunStatus::from_str(""), None);
- // Terminal grouping: completed/errored/cancelled are terminal; the two
- // live states are not.
- assert!(RunStatus::Completed.is_terminal());
- assert!(RunStatus::Errored.is_terminal());
- assert!(RunStatus::Cancelled.is_terminal());
- assert!(!RunStatus::Running.is_terminal());
- assert!(!RunStatus::Parked.is_terminal());
-
// Parked grouping: only `parked`.
assert!(RunStatus::Parked.is_parked());
for status in [
diff --git a/crates/core/src/db/message_fts.rs b/crates/core/src/db/message_fts.rs
index 2ee35daa..e6da9dab 100644
--- a/crates/core/src/db/message_fts.rs
+++ b/crates/core/src/db/message_fts.rs
@@ -61,6 +61,7 @@ mod tests {
system_prompt: String::new(),
thinking_level: None,
tools: Vec::new(),
+ external_tools: false,
}
}
diff --git a/crates/core/src/db/mod.rs b/crates/core/src/db/mod.rs
index 310ce0c6..f775d412 100644
--- a/crates/core/src/db/mod.rs
+++ b/crates/core/src/db/mod.rs
@@ -30,6 +30,7 @@ use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode, SqlitePoolOptions};
pub use intent_graph::{IntentGraphOutcome, apply_intent_graph_proposal, resolved_plan_for};
pub(crate) use intent_graph::validate_intent_graph_payload;
pub use lifecycle::Moved;
+pub use lifecycle::{InterruptedExternalCall, Terminal};
// `RunStatus` is the read+write Interface for Run status: the write verbs live on
// it (ADR-0028), and the read seam (`run_status`, `RunSnapshot.status`) now returns
// it too, so read sites match compiler-checked variants instead of raw strings
@@ -74,12 +75,13 @@ pub(crate) use queries::PartType;
// `RunSnapshot` is not re-exported: its one consumer (`run/subscribe`) reads
// fields off `select_run_snapshot`'s return without naming the type.
pub use runs::{
- AttachmentSeed, TimelineStep, append_assistant_part, assistant_message_id_for_run,
- cancel_parked_run, cancel_running_run, complete_run, error_run, error_run_with_message,
- history_for_run, list_run_history, mark_run_running, open_assistant_part,
- persist_initial_run, persist_thread_with_first_run, persist_tool_call, prepare_retry,
- read_run_timeline, recover_interrupted_runs, resolve_tool_call, run_prompt_and_thread,
- run_status, run_workflow_snapshot, select_run_snapshot,
+ AttachmentSeed, ExternalToolFinish, TimelineStep, append_assistant_part,
+ assistant_message_id_for_run, begin_external_tool_call, cancel_parked_run, cancel_running_run,
+ complete_run, error_run, error_run_with_message, finish_external_tool_call, history_for_run,
+ list_run_history, mark_run_running, open_assistant_part, persist_initial_run,
+ persist_thread_with_first_run, persist_tool_call, prepare_retry, read_run_timeline,
+ recover_interrupted_runs, resolve_tool_call, run_prompt_and_thread, run_status,
+ run_workflow_snapshot, select_run_snapshot,
};
// Result/row types no caller names (`Backlinks`, `CurrentEntityRow`,
// `ResolvedEntityRef`) and the V0-internal GTD reads (`todos_by_*`, consumed
@@ -95,7 +97,7 @@ pub use entities_read::{
// binary-only crate an unreachable re-export trips `unused_imports`.
pub use threads::{
MessageSegment, archive_thread, get_thread_with_messages, list_archived_threads,
- list_threads, thread_exists, unarchive_thread, update_thread_title,
+ list_threads, run_live_segments, thread_exists, unarchive_thread, update_thread_title,
};
/// Current wall-clock time as ms since UNIX_EPOCH (the `*_at` columns).
diff --git a/crates/core/src/db/queries.rs b/crates/core/src/db/queries.rs
index bc0af633..74e13f43 100644
--- a/crates/core/src/db/queries.rs
+++ b/crates/core/src/db/queries.rs
@@ -2398,26 +2398,19 @@ where
pub(super) async fn select_run_snapshot<'e, E>(
executor: E,
run_id: Uuid,
-) -> sqlx::Result, String)>>
+) -> sqlx::Result)>>
where
E: Executor<'e, Database = Sqlite>,
{
- let row: Option<(Option, String)> = sqlx::query_as(
- "SELECT ( \
- SELECT group_concat(text, '') FROM ( \
- SELECT text FROM message_parts \
- WHERE message_id = m.id AND type = 'text' ORDER BY seq \
- ) \
- ) AS text, \
- r.status \
- FROM runs r \
- JOIN messages m ON m.run_id = r.id AND m.role = 'assistant' \
- WHERE r.id = ?1",
- )
- .bind(run_id.to_string())
- .fetch_optional(executor)
- .await?;
- Ok(row)
+ // `(status, error_message)` — naturally authoritative (`None` iff the Run
+ // does not exist), the property the errored-late-subscribe fix relies on.
+ // The assistant text is no longer read here: the `run/subscribe` timeline
+ // now rides the ordered segment `Snapshot` (review P1 #2), and `thread/get`
+ // assembles its own via `segment_timeline`.
+ sqlx::query_as("SELECT status, error_message FROM runs WHERE id = ?1")
+ .bind(run_id.to_string())
+ .fetch_optional(executor)
+ .await
}
/// Read the Workflow fields a Run snapshotted at its start (ADR-0024): the
@@ -2557,6 +2550,117 @@ where
.map(|_| ())
}
+/// Insert a pending EXTERNAL tool-call row ONLY while its Run is still
+/// `running` (external-task-views A4): the Worker executes MCP tools itself and
+/// its frames race the Run's terminal transitions. A started frame that arrives
+/// after the Run was cancelled/errored must NOT land an orphan pending row, so
+/// the insert is guarded on the Run's live status. Returns rows affected (1 =
+/// inserted, 0 = the Run was already terminal → the caller publishes nothing).
+pub(super) async fn insert_external_tool_call_if_running<'e, E>(
+ executor: E,
+ id: &str,
+ run_id: Uuid,
+ name: &str,
+ request_payload: &str,
+ now_ms: i64,
+) -> sqlx::Result
+where
+ E: Executor<'e, Database = Sqlite>,
+{
+ Ok(sqlx::query(
+ "INSERT INTO tool_calls (id, run_id, name, request_payload, status, requested_at) \
+ SELECT ?, ?, ?, ?, 'pending', ? \
+ WHERE EXISTS (SELECT 1 FROM runs WHERE id = ? AND status = 'running')",
+ )
+ .bind(id)
+ .bind(run_id.to_string())
+ .bind(name)
+ .bind(request_payload)
+ .bind(now_ms)
+ .bind(run_id.to_string())
+ .execute(executor)
+ .await?
+ .rows_affected())
+}
+
+/// Resolve an EXTERNAL tool-call row, guarded on `run_id` AND `status='pending'`
+/// (external-task-views A4). Scoping by `run_id` means a stray id can never
+/// resolve another Run's row; the `pending` guard means a finished frame that
+/// races a terminal settle (cancel/EOF, which flips the row to `errored` with
+/// the interrupted result) matches 0 rows and loses — it can never clobber a
+/// settled row to a success-shaped result. `RETURNING name` hands back the
+/// resolved row's tool name (`Some` = won), so the caller publishes the finished
+/// event without tracking id→name pairings itself — the pending guard is the one
+/// pairing authority (review M1).
+pub(super) async fn resolve_external_tool_call<'e, E>(
+ executor: E,
+ id: &str,
+ run_id: Uuid,
+ status: &str,
+ result_payload: &str,
+ now_ms: i64,
+) -> sqlx::Result>
+where
+ E: Executor<'e, Database = Sqlite>,
+{
+ sqlx::query_scalar(
+ "UPDATE tool_calls SET status = ?, result_payload = ?, resolved_at = ? \
+ WHERE id = ? AND run_id = ? AND status = 'pending' \
+ RETURNING name",
+ )
+ .bind(status)
+ .bind(result_payload)
+ .bind(now_ms)
+ .bind(id)
+ .bind(run_id.to_string())
+ .fetch_optional(executor)
+ .await
+}
+
+/// Read the status of one external call scoped to its Run. Used only after a
+/// guarded resolve matched no pending row, to distinguish settled from missing.
+pub(super) async fn external_tool_call_status<'e, E>(
+ executor: E,
+ id: &str,
+ run_id: Uuid,
+) -> sqlx::Result>
+where
+ E: Executor<'e, Database = Sqlite>,
+{
+ sqlx::query_scalar("SELECT status FROM tool_calls WHERE id = ? AND run_id = ?")
+ .bind(id)
+ .bind(run_id.to_string())
+ .fetch_optional(executor)
+ .await
+}
+
+/// Settle every still-pending EXTERNAL (`ticktick_*`) call of a terminating
+/// Run with the Core-generated interrupted result. Returns the settled
+/// `(id, name)` pairs for post-commit publication.
+pub(super) async fn settle_pending_external_tool_calls<'e, E>(
+ executor: E,
+ run_id: Uuid,
+ result_payload: &str,
+ now_ms: i64,
+) -> sqlx::Result>
+where
+ E: Executor<'e, Database = Sqlite>,
+{
+ let prefix = crate::tools::EXTERNAL_TOOL_PREFIX;
+ sqlx::query_as(
+ "UPDATE tool_calls SET status = 'errored', result_payload = ?, resolved_at = ? \
+ WHERE run_id = ? AND status = 'pending' AND substr(name, 1, ?) = ? \
+ RETURNING id, name",
+ )
+ .bind(result_payload)
+ .bind(now_ms)
+ .bind(run_id.to_string())
+ .bind(prefix.len() as i64)
+ .bind(prefix)
+ .fetch_all(executor)
+ .await
+}
+
/// Insert a `run_steps` row of kind `tool_call`, interleaving the tool call
/// into the Run timeline at `seq`.
pub(super) async fn insert_tool_call_run_step<'e, E>(
@@ -2634,7 +2738,7 @@ where
{
sqlx::query_as(
"SELECT rs.kind, mp.text, \
- tc.name, tc.status, tc.request_payload, \
+ tc.id, tc.name, tc.status, tc.request_payload, tc.result_payload, \
p.id, p.mutation_kind, p.status, \
mp.type, \
( \
@@ -2663,45 +2767,51 @@ where
.bind(assistant_message_id)
.fetch_all(executor)
.await
- .map(|rows: Vec<(_, _, _, _, _, _, _, _, _, Option, Option, i64)>| {
- rows.into_iter()
- .map(
- |(
- kind,
- part_text,
- tc_name,
- tc_status,
- request_payload,
- proposal_id,
- mutation_kind,
- proposal_status,
- part_type,
- duration_to_next,
- run_ended_at,
- step_created_at,
- )| {
- // Resolve the reasoning span at the seam: the next step's
- // delta if there is one, else `run.ended_at − created_at`.
- // A negative span (clock skew) or an unknown end → None.
- let duration_ms = duration_to_next
- .or_else(|| run_ended_at.map(|end| end - step_created_at))
- .filter(|&d| d >= 0);
- SegmentTimelineRow {
+ .map(
+ |rows: Vec<(_, _, _, _, _, _, _, _, _, _, _, Option, Option, i64)>| {
+ rows.into_iter()
+ .map(
+ |(
kind,
part_text,
- part_type,
+ tool_call_id,
tc_name,
tc_status,
request_payload,
+ result_payload,
proposal_id,
mutation_kind,
proposal_status,
- duration_ms,
- }
- },
- )
- .collect()
- })
+ part_type,
+ duration_to_next,
+ run_ended_at,
+ step_created_at,
+ )| {
+ // Resolve the reasoning span at the seam: the next step's
+ // delta if there is one, else `run.ended_at − created_at`.
+ // A negative span (clock skew) or an unknown end → None.
+ let duration_ms = duration_to_next
+ .or_else(|| run_ended_at.map(|end| end - step_created_at))
+ .filter(|&d| d >= 0);
+ SegmentTimelineRow {
+ kind,
+ part_text,
+ part_type,
+ tool_call_id,
+ tc_name,
+ tc_status,
+ request_payload,
+ result_payload,
+ proposal_id,
+ mutation_kind,
+ proposal_status,
+ duration_ms,
+ }
+ },
+ )
+ .collect()
+ },
+ )
}
/// One row of the [`segment_timeline`] walk, named so the caller
@@ -2714,9 +2824,11 @@ pub(super) struct SegmentTimelineRow {
pub kind: String,
pub part_text: Option,
pub part_type: Option,
+ pub tool_call_id: Option,
pub tc_name: Option,
pub tc_status: Option,
pub request_payload: Option,
+ pub result_payload: Option,
pub proposal_id: Option,
pub mutation_kind: Option,
pub proposal_status: Option,
diff --git a/crates/core/src/db/runs.rs b/crates/core/src/db/runs.rs
index aa735304..4871ffa3 100644
--- a/crates/core/src/db/runs.rs
+++ b/crates/core/src/db/runs.rs
@@ -9,7 +9,7 @@ use uuid::Uuid;
// Lifecycle types come through the facade's re-exports (mod.rs keeps their
// ADR-0028/0029 annotations), not `super::lifecycle` directly, so the facade
// surface stays the one import path.
-use super::{Moved, ProposalStatus, RunStatus, TerminalReason};
+use super::{Moved, ProposalStatus, RunStatus, Terminal, TerminalReason};
use super::queries::{self, PartType};
use super::run_log;
use crate::workflow::Workflow;
@@ -345,6 +345,83 @@ pub async fn resolve_tool_call(
queries::resolve_tool_call(pool, tool_call_id, status, result_payload, now_ms).await
}
+/// Begin an EXTERNAL (Worker-executed MCP) tool call (external-task-views A4):
+/// persist the pending row + its `run_steps` entry in one transaction, GUARDED
+/// so the insert lands only while the Run is still `running`. Returns
+/// [`Moved::Won`] when the row was inserted, [`Moved::Lost`] when the Run had
+/// already gone terminal (a started frame that raced cancellation/EOF) — the
+/// caller publishes the started event ONLY on a win, so a phantom row can never
+/// reach a client.
+pub async fn begin_external_tool_call(
+ pool: &SqlitePool,
+ run_id: Uuid,
+ tool_call_id: &str,
+ name: &str,
+ request_payload: &str,
+ now_ms: i64,
+) -> sqlx::Result {
+ let mut tx = pool.begin().await?;
+ let inserted = queries::insert_external_tool_call_if_running(
+ &mut *tx,
+ tool_call_id,
+ run_id,
+ name,
+ request_payload,
+ now_ms,
+ )
+ .await?;
+ if inserted == 0 {
+ // The Run is no longer running — no row, no step, no event.
+ return Ok(Moved::Lost);
+ }
+ let seq = queries::next_run_step_seq(&mut *tx, run_id).await?;
+ queries::insert_tool_call_run_step(&mut *tx, run_id, seq, tool_call_id, now_ms).await?;
+ tx.commit().await?;
+ Ok(Moved::Won)
+}
+
+/// The authoritative outcome of pairing an external finished frame with its
+/// durable started row.
+#[derive(Debug, PartialEq, Eq)]
+pub enum ExternalToolFinish {
+ Resolved(String),
+ AlreadySettled,
+ Missing,
+}
+
+/// Finish an EXTERNAL tool call, distinguishing a resolved pending row from an
+/// already-settled row and a frame that was never started. The update + fallback
+/// classification share one transaction, so cancellation cannot change the
+/// answer between them.
+pub async fn finish_external_tool_call(
+ pool: &SqlitePool,
+ run_id: Uuid,
+ tool_call_id: &str,
+ status: &str,
+ result_payload: &str,
+ now_ms: i64,
+) -> sqlx::Result {
+ let mut tx = pool.begin().await?;
+ let resolved = queries::resolve_external_tool_call(
+ &mut *tx,
+ tool_call_id,
+ run_id,
+ status,
+ result_payload,
+ now_ms,
+ )
+ .await?;
+ let outcome = match resolved {
+ Some(name) => ExternalToolFinish::Resolved(name),
+ None => match queries::external_tool_call_status(&mut *tx, tool_call_id, run_id).await? {
+ Some(_) => ExternalToolFinish::AlreadySettled,
+ None => ExternalToolFinish::Missing,
+ },
+ };
+ tx.commit().await?;
+ Ok(outcome)
+}
+
/// Read a Run's [`RunStatus`] (ADR-0025); `None` when the Run does not exist.
/// Backs `run/subscribe`'s parked branch and the forwarder's no-false-done check.
///
@@ -406,18 +483,21 @@ pub async fn cancel_parked_run(pool: &SqlitePool, run_id: Uuid, now_ms: i64) ->
Ok(true)
}
-/// Cancel a running Run in one guarded transition. Returns `Won` only if the
-/// Run was still `running`; a lost race means a Worker terminal transition got
-/// there first and the caller maps the cancel request to `already_terminal`.
+/// Cancel a running Run in one guarded transition. Wins only if the Run was
+/// still `running`; a lost race means a Worker terminal transition got there
+/// first and the caller maps the cancel request to `already_terminal`. The won
+/// transition also settles still-pending external calls as interrupted
+/// (external-task-views A4) — the returned [`Terminal`] carries them for the
+/// post-commit `tool_call` event publishes.
pub async fn cancel_running_run(
pool: &SqlitePool,
run_id: Uuid,
now_ms: i64,
-) -> sqlx::Result {
+) -> sqlx::Result {
let mut tx = pool.begin().await?;
- let moved = RunStatus::cancel_running(&mut *tx, run_id, now_ms).await?;
+ let terminal = RunStatus::cancel_running(&mut *tx, run_id, now_ms).await?;
tx.commit().await?;
- Ok(moved)
+ Ok(terminal)
}
/// Prepare an errored Run for in-place retry (ADR-0028 retry amendment, #230) in
@@ -596,22 +676,24 @@ pub async fn read_run_timeline(pool: &SqlitePool, run_id: Uuid) -> sqlx::Result<
Ok(steps)
}
-/// A Run's snapshot for `run/subscribe` (ADR-0022): the assistant message's
-/// cumulative text at the subscribe instant plus the Run's status. `text` is
-/// empty for a Run that has streamed no delta yet.
+/// A Run's terminal-state snapshot for `run/subscribe` (ADR-0022): the Run's
+/// status + persisted error message at the subscribe instant. The assistant
+/// timeline now rides the ordered segment `Snapshot` (review P1 #2), so this no
+/// longer carries text.
#[derive(Debug)]
pub struct RunSnapshot {
- pub text: String,
- /// The Run's [`RunStatus`]. Part of the ADR-0022 snapshot shape; the
- /// subscribe handler reads it to tell terminal from live under the gate, and
- /// the `thread/get` rehydration read consumes it in a later slice.
+ /// The Run's [`RunStatus`]. The subscribe handler reads it under the gate to
+ /// tell terminal from live and pick the terminal event.
pub status: RunStatus,
+ /// The persisted `error_message` when the Run settled `errored` (`None`
+ /// otherwise). Lets `run/subscribe` emit a faithful `RunEvent::Error` for a
+ /// re-attach to an already-errored Run, rather than mis-reporting `done`.
+ pub error_message: Option,
}
-/// Read the snapshot-then-tail starting point: the assistant message's
-/// cumulative text (all `message_parts` concatenated in `seq` order) and the
-/// Run status. `None` when the Run does not exist (subscribe handler stays
-/// defensible against unknown run ids).
+/// Read the Run's status + error message. `None` when the Run does not exist
+/// (subscribe handler stays defensible against unknown run ids — the property
+/// the errored-late-subscribe fix relies on).
///
/// The stored status is parsed into [`RunStatus`] at this seam; an unknown value
/// surfaces as a loud `sqlx::Error::Decode` (see [`run_status`]).
@@ -619,14 +701,14 @@ pub async fn select_run_snapshot(
pool: &SqlitePool,
run_id: Uuid,
) -> sqlx::Result> {
- let Some((text, status)) = queries::select_run_snapshot(pool, run_id).await? else {
+ let Some((status, error_message)) = queries::select_run_snapshot(pool, run_id).await? else {
return Ok(None);
};
let status = RunStatus::from_str(&status)
.ok_or_else(|| sqlx::Error::Decode(format!("unknown stored run status {status:?}").into()))?;
Ok(Some(RunSnapshot {
- text: text.unwrap_or_default(),
status,
+ error_message,
}))
}
@@ -656,6 +738,7 @@ pub async fn run_workflow_snapshot(
thinking_level: Some(thinking_level),
system_prompt: base.system_prompt.clone(),
tools: base.tools.clone(),
+ external_tools: base.external_tools,
},
))
}
@@ -663,18 +746,18 @@ pub async fn run_workflow_snapshot(
/// Clean termination on the Worker's `done`: flip `runs` and the assistant
/// `messages` row to `completed` and append a `done` `run_log` row, in one
/// transaction so a reader never sees an in-between mix.
-pub async fn complete_run(pool: &SqlitePool, run_id: Uuid, now_ms: i64) -> sqlx::Result {
+pub async fn complete_run(pool: &SqlitePool, run_id: Uuid, now_ms: i64) -> sqlx::Result {
let mut tx = pool.begin().await?;
- let moved = RunStatus::complete(&mut *tx, run_id, now_ms).await?;
+ let terminal = RunStatus::complete(&mut *tx, run_id, now_ms).await?;
tx.commit().await?;
- Ok(moved)
+ Ok(terminal)
}
/// Worker stdout EOF without a `done` event (worker died/killed/hung up). Flip
/// `runs` to `errored` (`terminal_reason='worker_disconnected'`), every
/// `streaming` Message to `incomplete` (ADR-0017 invariant), and append an
/// `error` `run_log` row. One transaction.
-pub async fn error_run(pool: &SqlitePool, run_id: Uuid, now_ms: i64) -> sqlx::Result {
+pub async fn error_run(pool: &SqlitePool, run_id: Uuid, now_ms: i64) -> sqlx::Result {
error_run_with_message(
pool,
run_id,
@@ -698,13 +781,13 @@ pub async fn error_run_with_message(
error_code: &str,
error_message: &str,
now_ms: i64,
-) -> sqlx::Result {
+) -> sqlx::Result {
let mut tx = pool.begin().await?;
- let moved =
+ let terminal =
RunStatus::fail(&mut *tx, run_id, terminal_reason, error_code, error_message, now_ms)
.await?;
tx.commit().await?;
- Ok(moved)
+ Ok(terminal)
}
/// Boot recovery sweep (ADR-0012): on Core start, force-error every `running`
@@ -720,7 +803,7 @@ pub async fn recover_interrupted_runs(pool: &SqlitePool, now_ms: i64) -> sqlx::R
let mut swept: u64 = 0;
for id in queries::select_running_run_ids(&mut *tx).await? {
let run_id = Uuid::parse_str(&id).map_err(|e| sqlx::Error::Decode(e.into()))?;
- let moved = RunStatus::fail(
+ let terminal = RunStatus::fail(
&mut *tx,
run_id,
TerminalReason::CoreRestarted,
@@ -729,7 +812,7 @@ pub async fn recover_interrupted_runs(pool: &SqlitePool, now_ms: i64) -> sqlx::R
now_ms,
)
.await?;
- swept += moved.won() as u64;
+ swept += terminal.won() as u64;
}
tx.commit().await?;
Ok(swept)
@@ -943,15 +1026,79 @@ mod tests {
.expect("count run events")
}
+ /// The terminal settle (external-task-views A4) touches ONLY still-pending
+ /// EXTERNAL rows: a pending Core row stays pending (the reload filter owns
+ /// it, as before), and an already-resolved external row keeps its real
+ /// result. The boot recovery sweep — funnelled through the same
+ /// `RunStatus::fail` — settles too.
+ #[tokio::test]
+ async fn terminal_settle_interrupts_only_pending_external_rows() {
+ let pool = memory_pool().await;
+ let run_id = Uuid::parse_str("55555555-5555-4555-8555-555555555555").unwrap();
+ insert_bare_run(&pool, &run_id.to_string(), "running").await;
+ // Three rows: a pending external, a pending CORE, a completed external.
+ persist_tool_call(&pool, run_id, "tc-ext-pending", "ticktick_search_task", "{}", 1)
+ .await
+ .expect("pending external");
+ persist_tool_call(&pool, run_id, "tc-core-pending", "read_thread", "{}", 1)
+ .await
+ .expect("pending core");
+ persist_tool_call(&pool, run_id, "tc-ext-done", "ticktick_filter_tasks", "{}", 1)
+ .await
+ .expect("resolved external");
+ resolve_tool_call(
+ &pool,
+ "tc-ext-done",
+ "completed",
+ r#"{"content":[{"type":"text","text":"1 task found"}],"is_error":false}"#,
+ 2,
+ )
+ .await
+ .expect("resolve external");
+
+ // Boot recovery (RunStatus::fail funnel) is a terminal transition too.
+ let swept = recover_interrupted_runs(&pool, 42).await.expect("sweep");
+ assert_eq!(swept, 1);
+
+ let rows: Vec<(String, String, Option)> = sqlx::query_as(
+ "SELECT id, status, result_payload FROM tool_calls WHERE run_id = ?1 ORDER BY id",
+ )
+ .bind(run_id.to_string())
+ .fetch_all(&pool)
+ .await
+ .expect("read rows");
+ let by_id: std::collections::HashMap<&str, (&str, Option<&str>)> = rows
+ .iter()
+ .map(|(id, status, payload)| (id.as_str(), (status.as_str(), payload.as_deref())))
+ .collect();
+ assert_eq!(
+ by_id["tc-ext-pending"],
+ (
+ "errored",
+ Some(r#"{"content":[{"type":"text","text":"interrupted"}],"is_error":true}"#)
+ ),
+ "the pending external row settles as interrupted"
+ );
+ assert_eq!(
+ by_id["tc-core-pending"],
+ ("pending", None),
+ "a pending Core row is never touched"
+ );
+ assert_eq!(
+ by_id["tc-ext-done"].0, "completed",
+ "an already-resolved external row keeps its real result"
+ );
+ }
+
#[tokio::test]
async fn complete_loses_on_parked_and_writes_no_done_event() {
let pool = memory_pool().await;
let run_id = Uuid::parse_str("33333333-3333-4333-8333-333333333333").unwrap();
insert_bare_run(&pool, &run_id.to_string(), "parked").await;
- let moved = complete_run(&pool, run_id, 42).await.expect("complete");
+ let terminal = complete_run(&pool, run_id, 42).await.expect("complete");
- assert_eq!(moved, Moved::Lost);
+ assert!(!terminal.won());
assert_eq!(run_status_of(&pool, &run_id.to_string()).await, "parked");
assert_eq!(run_event_count(&pool, &run_id.to_string(), "done").await, 0);
}
@@ -962,9 +1109,9 @@ mod tests {
let run_id = Uuid::parse_str("44444444-4444-4444-8444-444444444444").unwrap();
insert_bare_run(&pool, &run_id.to_string(), "parked").await;
- let moved = error_run(&pool, run_id, 42).await.expect("error");
+ let terminal = error_run(&pool, run_id, 42).await.expect("error");
- assert_eq!(moved, Moved::Lost);
+ assert!(!terminal.won());
assert_eq!(run_status_of(&pool, &run_id.to_string()).await, "parked");
assert_eq!(
run_event_count(&pool, &run_id.to_string(), "error").await,
@@ -1309,18 +1456,13 @@ mod tests {
);
}
- /// The snapshot-composition rule (finding F9, the Core half): a Run's
- /// subscribe snapshot is the assistant message's CUMULATIVE text — all
- /// `type='text'` parts concatenated in `seq` order, reasoning excluded.
- /// CROSS-LANGUAGE MIRROR: the web client (`apps/web/src/store/chat.ts`
- /// `setCumulativeText` / the `appendTextSegment` armed path) assumes exactly
- /// this rule, because Core sends the snapshot as a plain `text_delta`
- /// (`runs/subscribe.rs` `send_text_delta(… &snap.text)` sites) —
- /// indistinguishable on the wire from a tail delta; only the client's armed
- /// bit disambiguates. Tagging the snapshot on the wire is the recorded
- /// follow-up (F9's full fix); until then this test tethers the two halves.
+ /// The assistant timeline's `type='text'` parts persist in `seq` order with
+ /// reasoning interleaved — the raw shape `run_live_segments` assembles into
+ /// the ordered `Snapshot` (review P1 #2), reasoning kept in place, text not
+ /// coalesced across it. (The `run/subscribe` wire tagging F9 flagged is now
+ /// the explicit `snapshot` Run Event.)
#[tokio::test]
- async fn select_run_snapshot_concats_text_parts_in_seq_order() {
+ async fn assistant_text_parts_persist_in_seq_order() {
let pool = memory_pool().await;
let thread_id = Uuid::now_v7();
let run_id = Uuid::now_v7();
@@ -1364,17 +1506,66 @@ mod tests {
queries::insert_text_part(&mut *tx, assistant_id, 2, "world")
.await
.expect("text part 2");
+ // The run_steps spine the segment assembler orders by (production writes
+ // part + step together via `open_assistant_part`).
+ for seq in 0..3 {
+ queries::insert_message_run_step(&mut *tx, run_id, seq, assistant_id, seq, 1)
+ .await
+ .expect("message run step");
+ }
tx.commit().await.expect("commit seed");
- let snap = select_run_snapshot(&pool, run_id)
+ // The assistant text parts concatenate in seq order, reasoning excluded.
+ // (`run_live_segments` now assembles these as SEPARATE ordered segments
+ // with reasoning interleaved — review P1 #2; here we pin the persisted
+ // parts directly.)
+ let text: Option = sqlx::query_scalar(
+ "SELECT group_concat(text, '') FROM ( \
+ SELECT text FROM message_parts \
+ WHERE message_id = ?1 AND type = 'text' ORDER BY seq )",
+ )
+ .bind(assistant_id.to_string())
+ .fetch_one(&pool)
+ .await
+ .expect("read text");
+ assert_eq!(
+ text.unwrap_or_default(),
+ "Hello world",
+ "text parts concatenate in seq order, reasoning excluded"
+ );
+ assert!(
+ run_status(&pool, run_id)
+ .await
+ .expect("status")
+ .expect("run exists")
+ .is_parked(),
+ "the seeded run is parked"
+ );
+
+ // The assembled timeline (the `run/subscribe` snapshot source) preserves
+ // the text–reasoning–text interleave as SEPARATE ordered segments.
+ let segments = crate::db::run_live_segments(&pool, run_id, true)
.await
- .expect("read ok")
- .expect("run exists");
+ .expect("assemble live segments");
+ let shape: Vec = segments
+ .iter()
+ .map(|seg| match seg {
+ crate::db::MessageSegment::Text { text } => format!("text:{text}"),
+ crate::db::MessageSegment::Reasoning { text, .. } => {
+ format!("reasoning:{text}")
+ }
+ other => format!("other:{other:?}"),
+ })
+ .collect();
assert_eq!(
- snap.text, "Hello world",
- "cumulative = all text parts, seq order, reasoning excluded"
+ shape,
+ vec![
+ "text:Hello ".to_string(),
+ "reasoning:thinking…".to_string(),
+ "text:world".to_string(),
+ ],
+ "run_live_segments keeps the interleave in seq order"
);
- assert!(snap.status.is_parked(), "status rides the snapshot");
}
/// Drive a bare Run to `errored` directly (terminal fields stamped), to seed
diff --git a/crates/core/src/db/threads.rs b/crates/core/src/db/threads.rs
index b0f76e4c..3e54b7ba 100644
--- a/crates/core/src/db/threads.rs
+++ b/crates/core/src/db/threads.rs
@@ -72,10 +72,16 @@ pub enum MessageSegment {
/// wire spelling (`errored`/anything-unexpected → `error`, `completed` →
/// `completed`) and the display `arg` derived from the request payload via the
/// same per-tool extractor the live `tool_call` Run Event uses.
+ /// `tool_call_id` is the durable per-call identity (external-task-views A4);
+ /// `result` is the normalized model-received content, decoded from
+ /// `result_payload` for external (`ticktick_*`) calls so the reload row
+ /// expands identically to the live one.
ToolCall {
+ tool_call_id: String,
name: String,
status: String,
arg: Option,
+ result: Option,
},
/// The decided Proposal the turn parked on (ADR-0044): `accepted`/`rejected`
/// only — pending/cancelled are skipped at assembly. `entity_id` (ADR-0044
@@ -105,6 +111,57 @@ pub enum MessageSegment {
},
}
+/// Map a db-side timeline item to its wire [`crate::protocol::Segment`] variant
+/// (1:1, order-preserving, ADR-0045). Used by `thread/get` rehydration AND the
+/// `run/subscribe` full-timeline snapshot (review P1 #2), so the reloaded and the
+/// live-snapshot timelines are assembled identically.
+impl From for crate::protocol::Segment {
+ fn from(segment: MessageSegment) -> Self {
+ use crate::protocol::Segment;
+ match segment {
+ MessageSegment::Text { text } => Segment::Text { text },
+ MessageSegment::ToolCall {
+ tool_call_id,
+ name,
+ status,
+ arg,
+ result,
+ } => Segment::ToolCall {
+ tool_call_id,
+ name,
+ status,
+ arg,
+ result,
+ },
+ MessageSegment::Proposal {
+ proposal_id,
+ mutation_kind,
+ status,
+ entity_id,
+ } => Segment::Proposal {
+ proposal_id,
+ mutation_kind,
+ status,
+ entity_id,
+ },
+ MessageSegment::Reasoning { text, duration_ms } => {
+ Segment::Reasoning { text, duration_ms }
+ }
+ MessageSegment::Attachment {
+ media_id,
+ mime,
+ width,
+ height,
+ } => Segment::Attachment {
+ media_id,
+ mime,
+ width,
+ height,
+ },
+ }
+ }
+}
+
/// One Message in a `thread/get` read. `segments` is the assistant turn's ordered
/// timeline (ADR-0045) — text/tool_call/proposal items in `run_steps` order; a user
/// Message carries a single `text` segment. Replaces the prior assembled flat
@@ -162,7 +219,9 @@ pub async fn get_thread_with_messages(
// `segment_rows_for_run`'s tolerant arg parsing) with a Diagnostic Log
// warning (ADR-0038) so the vanished image stays greppable.
let segments = if role == "assistant" {
- segment_rows_for_run(pool, &run_id, &id).await?
+ // thread/get reload excludes still-pending calls (owned by the live
+ // tail, ADR-0043); the live subscribe snapshot includes them (#2).
+ segment_rows_for_run(pool, &run_id, &id, false).await?
} else {
user_segments(&id, queries::parts_by_message(pool, &id).await?)
};
@@ -268,6 +327,7 @@ async fn segment_rows_for_run(
pool: &SqlitePool,
run_id: &str,
assistant_message_id: &str,
+ include_pending: bool,
) -> sqlx::Result> {
let Ok(run_uuid) = Uuid::parse_str(run_id) else {
return Ok(Vec::new());
@@ -287,9 +347,11 @@ async fn segment_rows_for_run(
kind,
part_text,
part_type,
+ tool_call_id,
tc_name,
tc_status,
request_payload,
+ result_payload,
proposal_id,
mutation_kind,
proposal_status,
@@ -340,11 +402,19 @@ async fn segment_rows_for_run(
});
}
} else if !crate::tools::is_proposal(&name) {
- // A non-Proposal tool call → a settled tool-activity row
- // (ADR-0043). Skip a `pending` call; map the persisted status to
- // the wire spelling, never leaking a non-vocabulary value.
+ // A non-Proposal tool call → a tool-activity row (ADR-0043).
+ // Map the persisted status to the wire spelling (never leaking
+ // a non-vocabulary value). thread/get (`include_pending=false`)
+ // SKIPS a `pending` call — its result is owned by the live tail;
+ // the `run/subscribe` snapshot (`include_pending=true`) keeps it
+ // as `running` so a reconnect shows the in-flight call (#2).
let status = tc_status.unwrap_or_default();
- if status != "pending" {
+ let wire_status = match status.as_str() {
+ "pending" => include_pending.then_some("running"),
+ "completed" => Some("completed"),
+ _ => Some("error"),
+ };
+ if let Some(wire_status) = wire_status {
// Derive the display arg from the stored request payload via
// the same per-tool extractor the live `tool_call` Run Event
// uses, so the reloaded row matches the live one. A malformed
@@ -353,14 +423,27 @@ async fn segment_rows_for_run(
.as_deref()
.and_then(|p| serde_json::from_str::(p).ok())
.and_then(|params| crate::tools::display_arg(&name, ¶ms));
+ // An external call's payload IS a TranscriptToolResult
+ // (the finished frame or the interrupted settle wrote
+ // it) — served so the reload row expands identically to
+ // the live one (A4). A pending call has none yet; Core-tool
+ // rows carry none in v1.
+ let result = if crate::tools::is_external(&name) {
+ result_payload.as_deref().and_then(|payload| {
+ serde_json::from_str::(
+ payload,
+ )
+ .ok()
+ })
+ } else {
+ None
+ };
segments.push(MessageSegment::ToolCall {
+ tool_call_id: tool_call_id.unwrap_or_default(),
name,
- status: if status == "completed" {
- "completed".to_string()
- } else {
- "error".to_string()
- },
+ status: wire_status.to_string(),
arg,
+ result,
});
}
}
@@ -371,6 +454,26 @@ async fn segment_rows_for_run(
Ok(segments)
}
+/// The run's ordered timeline for the `run/subscribe` full-timeline snapshot
+/// (review P1 #2): the SAME assembly `thread/get` uses. `include_pending` is the
+/// liveness gate (CodeRabbit #336): a LIVE hub renders still-pending calls as
+/// `running` (the in-flight external call a reconnect must show), while a run
+/// with NO live hub (terminal/parked) excludes them — a Core row orphaned
+/// `pending` by a crash would otherwise reach the Client as `running` on a
+/// finished Run, forever, and disagree with `thread/get`. Empty when the Run
+/// has no assistant message.
+pub async fn run_live_segments(
+ pool: &SqlitePool,
+ run_id: Uuid,
+ include_pending: bool,
+) -> sqlx::Result> {
+ let Some(assistant_message_id) = queries::assistant_message_id_for_run(pool, run_id).await?
+ else {
+ return Ok(Vec::new());
+ };
+ segment_rows_for_run(pool, &run_id.to_string(), &assistant_message_id, include_pending).await
+}
+
#[cfg(test)]
mod tests {
use crate::db::test_support::memory_pool;
@@ -381,6 +484,146 @@ mod tests {
};
use crate::workflow::Workflow;
+ /// External (`ticktick_*`) rows rehydrate with their durable
+ /// `tool_call_id` and the model-received `result` (external-task-views
+ /// A4): a completed row serves its TranscriptToolResult verbatim, and a
+ /// row the cancel transition settled renders as an ERROR carrying the
+ /// Core-generated interrupted result — the same object the live
+ /// interrupted `tool_call` event carried, so live and reload agree by
+ /// construction. Core-tool rows carry `result: None` in v1.
+ #[tokio::test]
+ async fn thread_get_serves_external_results_and_interrupted_settle() {
+ let pool = memory_pool().await;
+ let thread_id = Uuid::now_v7();
+ let run_id = Uuid::now_v7();
+ let assistant_id = Uuid::now_v7();
+
+ let mut tx = pool.begin().await.expect("begin");
+ queries::insert_thread(&mut *tx, thread_id, "T", 1)
+ .await
+ .expect("thread");
+ sqlx::query(
+ "INSERT INTO runs \
+ (id, thread_id, workflow_name, workflow_version, provider, model, \
+ thinking_level, user_message_id, status, started_at) \
+ VALUES (?, ?, 'w', '1', 'p', 'm', 'off', ?, 'running', 1)",
+ )
+ .bind(run_id.to_string())
+ .bind(thread_id.to_string())
+ .bind(assistant_id.to_string())
+ .execute(&mut *tx)
+ .await
+ .expect("run");
+ queries::insert_message(
+ &mut *tx,
+ assistant_id,
+ thread_id,
+ run_id,
+ "assistant",
+ "streaming",
+ 1,
+ )
+ .await
+ .expect("assistant message");
+ tx.commit().await.expect("commit seed");
+
+ // A completed external call with its TranscriptToolResult payload…
+ persist_tool_call(
+ &pool,
+ run_id,
+ "tc-ext-ok",
+ "ticktick_filter_tasks",
+ r#"{"filter":{"status":[0]}}"#,
+ 2,
+ )
+ .await
+ .expect("persist external");
+ resolve_tool_call(
+ &pool,
+ "tc-ext-ok",
+ "completed",
+ r#"{"content":[{"type":"text","text":"1 task found"}],"is_error":false}"#,
+ 3,
+ )
+ .await
+ .expect("resolve external");
+ // …a Core call (result never served in v1)…
+ persist_tool_call(&pool, run_id, "tc-core", "read_thread", "{}", 4)
+ .await
+ .expect("persist core");
+ resolve_tool_call(&pool, "tc-core", "completed", r#"{"content":[]}"#, 5)
+ .await
+ .expect("resolve core");
+ // …and a still-pending external call the REAL cancel transition settles.
+ persist_tool_call(
+ &pool,
+ run_id,
+ "tc-ext-hang",
+ "ticktick_search_task",
+ "{}",
+ 6,
+ )
+ .await
+ .expect("persist pending external");
+ let terminal = crate::db::cancel_running_run(&pool, run_id, 7)
+ .await
+ .expect("cancel");
+ let crate::db::Terminal::Won { interrupted } = terminal else {
+ panic!("cancel won the terminal transition");
+ };
+ assert_eq!(interrupted.len(), 1);
+
+ let (_, messages) = get_thread_with_messages(&pool, thread_id)
+ .await
+ .expect("thread/get")
+ .expect("thread exists");
+ let assistant = messages
+ .iter()
+ .find(|m| m.role == "assistant")
+ .expect("assistant row");
+ let tool_calls: Vec<_> = assistant
+ .segments
+ .iter()
+ .filter_map(|s| match s {
+ MessageSegment::ToolCall {
+ tool_call_id,
+ name,
+ status,
+ result,
+ ..
+ } => Some((
+ tool_call_id.as_str(),
+ name.as_str(),
+ status.as_str(),
+ result.clone(),
+ )),
+ _ => None,
+ })
+ .collect();
+ assert_eq!(
+ tool_calls,
+ vec![
+ (
+ "tc-ext-ok",
+ "ticktick_filter_tasks",
+ "completed",
+ Some(crate::protocol::TranscriptToolResult::text(
+ "1 task found",
+ false
+ )),
+ ),
+ ("tc-core", "read_thread", "completed", None),
+ (
+ "tc-ext-hang",
+ "ticktick_search_task",
+ "error",
+ Some(crate::protocol::TranscriptToolResult::interrupted()),
+ ),
+ ],
+ "external rows serve id + result; the settled row renders as an interrupted error"
+ );
+ }
+
/// ADR-0045: `thread/get` rehydrates the assistant turn's ORDERED `segments[]`
/// from `run_steps` in seq order — text/tool_call/proposal interleaved as they
/// happened. Folds in the ADR-0043 rules (a non-Proposal tool call rehydrates as
@@ -517,15 +760,25 @@ mod tests {
other => panic!("segment[0] is the text segment, got {other:?}"),
}
match &assistant.segments[1] {
- MessageSegment::ToolCall { name, status, arg } => {
+ MessageSegment::ToolCall {
+ tool_call_id,
+ name,
+ status,
+ arg,
+ result,
+ } => {
+ assert!(!tool_call_id.is_empty(), "the durable per-call id is served");
assert_eq!(name, "search_entities");
assert_eq!(status, "completed");
assert_eq!(arg.as_deref(), Some("Lev"));
+ assert_eq!(*result, None, "a Core-tool row carries no result in v1");
}
other => panic!("segment[1] is the completed search, got {other:?}"),
}
match &assistant.segments[2] {
- MessageSegment::ToolCall { name, status, arg } => {
+ MessageSegment::ToolCall {
+ name, status, arg, ..
+ } => {
assert_eq!(name, "search_entities");
// `errored` maps to the wire `error` spelling.
assert_eq!(status, "error");
@@ -1866,6 +2119,7 @@ mod tests {
system_prompt: String::new(),
thinking_level: None,
tools: Vec::new(),
+ external_tools: false,
}
}
diff --git a/crates/core/src/hub.rs b/crates/core/src/hub.rs
index 7a492023..23167bf1 100644
--- a/crates/core/src/hub.rs
+++ b/crates/core/src/hub.rs
@@ -10,7 +10,7 @@
use std::collections::HashMap;
use std::future::Future;
-use std::sync::{Arc, Mutex};
+use std::sync::{Arc, Mutex, Weak};
use tokio::sync::{broadcast, watch};
use uuid::Uuid;
@@ -28,8 +28,8 @@ const HUB_BUFFER: usize = 256;
/// exclusive with the subscribe handler's `snapshot → attach`, so every delta
/// falls wholly before or after a subscribe instant (ADR-0022 exactly-once).
/// Both are private: the gate ritual lives behind this type's methods
-/// ([`Self::gate`], [`Self::publish_gated`], [`Self::snapshot_then_attach`],
-/// [`Self::send`]) so no call site re-spells the lock ordering. `cancel_tx` is
+/// ([`Self::gate`], [`Self::snapshot_then_attach`], [`Self::send`]) so no call
+/// site re-spells the lock ordering. `cancel_tx` is
/// the in-memory signal Core flips after durably winning a cancellation; the
/// Worker loop observes it and stops.
#[derive(Clone)]
@@ -52,45 +52,48 @@ impl RunHub {
/// Acquire the ADR-0022 per-run gate. The returned guard makes the caller's
/// `persist → publish` (or `snapshot → attach`) critical section mutually
- /// exclusive with the other side's. Prefer the shaped helpers
- /// ([`Self::publish_gated`], [`Self::snapshot_then_attach`]); this exists
- /// for multi-step brackets the closures can't express (e.g. the Worker's
- /// cancel-check-then-send tool-call brackets).
+ /// exclusive with the other side's. Held directly across a persist/settle tx
+ /// AND one or more raw [`Self::send`]s — the terminal-settlement bracket
+ /// (review P1 #3: settle → interrupted → terminal, one acquisition) — or
+ /// paired with [`Self::snapshot_then_attach`] on the subscribe side. NOT
+ /// re-entrant, so publish via raw `send` while holding it, never a nested
+ /// `gate()`.
pub async fn gate(&self) -> tokio::sync::MutexGuard<'_, ()> {
self.gate.lock().await
}
- /// `lock → send → unlock`: the terminal/ephemeral publish ritual (ADR-0022).
- pub async fn publish_gated(&self, event: RunEvent) {
- let guard = self.gate.lock().await;
- let _ = self.tx.send(event);
- drop(guard);
+ /// The gate as an OWNED guard (`Arc`-backed), for [`activate`]'s candidate
+ /// lock: it must outlive the registration loop's borrow scope.
+ async fn gate_owned(&self) -> tokio::sync::OwnedMutexGuard<()> {
+ self.gate.clone().lock_owned().await
}
/// `lock → snapshot (caller's async read) → attach receiver → unlock` —
/// ADR-0022 snapshot-then-tail. The read runs under the gate, so every
/// delta falls wholly before or after the subscribe instant (in the
- /// snapshot or on the tail, never both, never neither).
- pub async fn snapshot_then_attach(
- &self,
- read: F,
- ) -> (T, broadcast::Receiver)
+ /// snapshot or on the tail, never both, never neither). Returns a
+ /// [`RunTail`] that owns the receiver + gate (no `Sender`), so the caller
+ /// can `recover()` from a lag under the gate without keeping the channel open.
+ pub async fn snapshot_then_attach(&self, read: F) -> (T, RunTail)
where
F: FnOnce() -> Fut,
Fut: Future