Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts: # .gitignore # apps/cli/package.json # apps/cli/src/web.ts # docs/architecture.i18n.yaml # docs/config-catalog.md # docs/module-graph.md # packages/client/connection/README.md # packages/client/connection/src/client/api.ts # packages/client/connection/src/client/fixture.ts # packages/client/runtime/README.md # packages/client/runtime/src/client/sessions/service.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/runtime/src/client/workspaces/service.ts # packages/client/ui-conversation/src/client/apply.ts # packages/client/ui-conversation/src/client/chat/MessageItem.tsx # packages/client/ui-conversation/src/client/contract/slots.ts # packages/client/ui-conversation/src/client/index.ts # packages/client/ui-conversation/src/client/service.ts # packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx # packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx # packages/client/ui-conversation/src/client/skeleton/EmptyState.tsx # packages/client/ui-conversation/src/client/skeleton/InputBar.module.css # packages/client/ui-conversation/src/client/skeleton/InputBar.tsx # packages/client/ui-conversation/tests/apply-inject.spec.tsx # packages/client/ui-conversation/tests/input-bar.spec.tsx # packages/client/ui-conversation/tests/skeleton.spec.tsx # packages/client/ui-trajectory/tests/views.spec.tsx # packages/host/apiproxy/src/api-proxy.ts # pnpm-lock.yaml
2026-07-27 12:27:30 +08:00
parent 1a27c0f779 79eb3a9035
commit b599d1d0af
1799 changed files with 63595 additions and 13464 deletions
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -859,7 +859,7 @@ set(agent: Agent, active: boolean): void

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/plan/plan-mode/src/index.ts:142`](../../packages/plan/plan-mode/src/index.ts)
+Source: [`packages/plan/plan-mode/src/index.ts:141`](../../packages/plan/plan-mode/src/index.ts)

 ## `ctx.pty` — `PtyService`

@@ -1041,15 +1041,17 @@ abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEven
 * This read is serialized with writes for the same id and returns detached
 * values, so observers cannot mutate backend-owned state.
 * @param id - the persisted session to inspect.
+ * @param signal - optional cancellation for queued and backend read work.
 * @returns the header and valid stored event prefix exactly as observed.
 */
-abstract inspect(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>

 /**
 * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
 * @returns one header per materialized session.
 */
-abstract list(): Promise<SessionHeader[]>
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>

 /**
 * List materialized sessions with cheap per-log change tokens.
@@ -1058,9 +1060,10 @@ abstract list(): Promise<SessionHeader[]>
 * successful mutating {@link load} repair changes the next listed revision.
 * Revisions also distinguish independently backed stores so backend-local
 * counters cannot compare equal across different persistence sources.
+ * @param signal - optional cancellation for backend snapshot-listing work.
 * @returns one header and opaque revision per materialized session without loading full logs.
 */
-abstract listSnapshots(): Promise<SessionPersistenceSnapshot[]>
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
 ```

 Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionLocation](../core-data-structures/persistence.md) · [SessionPersistenceSnapshot](../core-data-structures/persistence.md)
@@ -1086,15 +1089,16 @@ abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExec
 * Search events within one live-preferred logical session.
 * @param request - target session, query text, filters, page size, and cursor.
 * @param exec - optional cancellation control.
- * @returns matching event hits in deterministic relevance order.
+ * @returns matching event hits and their target header from one indexed generation.
 */
-abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionEventSearchHit>>
+abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>

 /**
 * List the complete logical corpus using live-preferred records.
+ * @param signal - optional cancellation for persistence listing.
 * @returns deterministic newest-first cloned session records.
 */
-listSessions(): Promise<SessionRecord[]>
+listSessions(signal?: AbortSignal): Promise<SessionRecord[]>

 /**
 * Read and replay-validate one complete logical session log without making it live.
@@ -1107,16 +1111,37 @@ async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>
 /**
 * Filter the complete logical corpus with provider-independent predicates.
 * @param filters - ANDed session metadata and availability clauses.
+ * @param signal - optional cancellation for persistence listing.
 * @returns matching cloned records in deterministic newest-first order.
 */
-async filterSessions(filters: readonly SessionResultFilter[]): Promise<SessionRecord[]>
+async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>

 /**
 * Fold the latest log-backed title from one live-preferred logical session.
 * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
 * @returns latest title snapshot, or `undefined` when the log has no title event.
 */
-async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined>
+async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>
+
+/**
+ * Fold the latest title and return its source header from one corpus observation.
+ * @param sessionId - live or persisted session id to read.
+ * @param signal - optional cancellation for source resolution and title folding.
+ * @returns cloned source header and optional latest title snapshot.
+ */
+async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>
+
+/**
+ * Fold titles for unique sessions from one cancellable corpus observation.
+ *
+ * Results preserve first-occurrence input order. Operational failures stay
+ * isolated per session, while cancellation rejects the complete operation.
+ * @param sessionIds - live or persisted session ids to observe.
+ * @param signal - optional cancellation shared by all source reads.
+ * @returns one fulfilled or rejected result per unique requested id.
+ */
+async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>

 /**
 * List lightweight raw-log event records for one logical session.
@@ -1144,30 +1169,33 @@ async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>
 /**
 * Trace known ancestry and descendants from one corpus observation.
 * @param sessionId - logical session id to trace.
+ * @param signal - optional cancellation for persistence listing.
 * @returns a complete lineage or an explicit unresolved parent boundary.
 * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
 */
-async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>
+async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>

 /**
 * Trace one event's direct positional and provenance relationships.
 * @param request - target session id and event seq.
- * @returns direct links plus the target's positional replacement chain.
+ * @param signal - optional cancellation for persisted source resolution.
+ * @returns source header, direct links, and the target's positional replacement chain.
 * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
 */
-async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
+async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>

 /**
 * Read one full event plus a bounded raw-log context window.
 * @param request - target session/seq and context sizes.
+ * @param signal - optional cancellation for persisted source resolution.
 * @returns cloned target and neighboring events.
 */
-async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
+async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>
 ```

-Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventResultFilter](../core-data-structures/session-query.md) · [SessionEventSearchDocument](../core-data-structures/session-query.md) · [SessionEventSearchHit](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionLogSnapshot](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionResultFilter](../core-data-structures/session-query.md) · [SessionSearchExecContext](../core-data-structures/session-query.md) · [SessionSearchHit](../core-data-structures/session-query.md) · [SessionSearchPage](../core-data-structures/session-query.md) · [SessionSearchRequest](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)
+Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventResultFilter](../core-data-structures/session-query.md) · [SessionEventSearchDocument](../core-data-structures/session-query.md) · [SessionEventSearchPage](../core-data-structures/session-query.md) · [SessionEventSearchRequest](../core-data-structures/session-query.md) · [SessionEventTraceObservation](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionLogSnapshot](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md) · [SessionResultFilter](../core-data-structures/session-query.md) · [SessionSearchExecContext](../core-data-structures/session-query.md) · [SessionSearchHit](../core-data-structures/session-query.md) · [SessionSearchPage](../core-data-structures/session-query.md) · [SessionSearchRequest](../core-data-structures/session-query.md) · [SessionSurfaceSnapshot](../core-data-structures/session-query.md) · [SessionTitleObservation](../core-data-structures/session-query.md) · [SessionTitleObservationResult](../core-data-structures/session-query.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)

-Source: [`packages/session-query/session-query/src/index.ts:74`](../../packages/session-query/session-query/src/index.ts)
+Source: [`packages/session-query/session-query/src/index.ts:81`](../../packages/session-query/session-query/src/index.ts)

 ## `ctx.sessionReferences` — `SessionReferenceService`

@@ -1611,9 +1639,16 @@ Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptSec

 Source: [`packages/core/system-prompt/src/index.ts:246`](../../packages/core/system-prompt/src/index.ts)

-## `ctx.tasks` — `TaskService`
+## `ctx.tasks` — `TaskService` (abstract seam)

-The `tasks` service: the runtime-global background task registry. See the module doc for the ownership, isolation, and lifecycle contracts.
+Abstract background task registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.tasks` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+
+Implementations must honor these semantics:
+
+- Registrations outlive producer and control-surface fibers. Owner and service disposal cancel live work and await compliant producers; a throwing teardown cancel force-fails only the record.
+- Owned-task access is fenced by the owner's session id. Ids are predictable, so authorization — not secrecy — is the boundary.
+- Settlement is first-wins: one terminal record, one round of contained listener notification, and released waiters, even against a late producer outcome.
+- start refuses work while no control surface is attached, so a producer cannot start work that callers cannot collect or stop.

 ```ts cordis-catalog
 /**
@@ -1624,7 +1659,7 @@ The `tasks` service: the runtime-global background task registry. See the module
 * @param spec - task identity, owner, and synchronous starter.
 * @returns the registry-issued `<kind>-N` id.
 */
-start(spec: TaskStart): TaskId
+abstract start(spec: TaskStart): TaskId

 /**
 * List caller-owned and unowned tasks in registration order without exposing
@@ -1632,7 +1667,7 @@ start(spec: TaskStart): TaskId
 * @param caller - reading agent; a non-agent caller sees only unowned tasks.
 * @returns fresh snapshots.
 */
-list(caller?: Agent): TaskSnapshot[]
+abstract list(caller?: Agent): TaskSnapshot[]

 /**
 * Return a non-consuming snapshot without changing its read cursor or notice
@@ -1641,7 +1676,7 @@ list(caller?: Agent): TaskSnapshot[]
 * @param caller - reading agent checked against the owner.
 * @returns a fresh snapshot.
 */
-get(id: TaskId, caller?: Agent): TaskSnapshot
+abstract get(id: TaskId, caller?: Agent): TaskSnapshot

 /**
 * Read the next stream delta, or the idempotent final output after settlement.
@@ -1651,7 +1686,7 @@ get(id: TaskId, caller?: Agent): TaskSnapshot
 * @param caller - reading agent checked against the owner.
 * @returns output text and the post-read snapshot.
 */
-read(id: TaskId, caller?: Agent): TaskRead
+abstract read(id: TaskId, caller?: Agent): TaskRead

 /**
 * Request cancellation, then mark the task stopping and reported. A producer
@@ -1662,21 +1697,20 @@ read(id: TaskId, caller?: Agent): TaskRead
 * @param reason - logged reason forwarded to the producer.
 * @returns `requested` for live work, otherwise `already-finished`.
 */
-kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
+abstract kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'

 /**
 * Wait for settlement or timeout without cancelling the task. Caller abort
- * rejects only while the task is live; after settlement it returns the
- * terminal snapshot so a notice suppressed for this waiter is still delivered.
- * Timed-out and aborted waits detach their resolvers. Throws for invalid,
- * unknown, or foreign input.
+ * rejects only while the task is live; after settlement the terminal
+ * snapshot wins so a notice suppressed for this waiter is still delivered.
+ * Throws for invalid, unknown, or foreign input.
 * @param id - task to wait for.
 * @param timeoutMs - positive finite wait bound in milliseconds.
 * @param caller - waiting agent checked against the owner.
 * @param signal - optional cancellation of the wait itself.
 * @returns snapshot at settlement or timeout.
 */
-async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
+abstract wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>

 /**
 * Register an effect-scoped completion listener. Each listener is contained;
@@ -1685,7 +1719,7 @@ async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal):
 * @param listener - receives each terminal snapshot and its exact owner.
 * @returns disposer that unregisters the listener.
 */
-onTaskDone(listener: TaskDoneListener): () => void
+abstract onTaskDone(listener: TaskDoneListener): () => void

 /**
 * Attach an effect-scoped surface that can read and stop tasks. {@link start}
@@ -1693,12 +1727,12 @@ onTaskDone(listener: TaskDoneListener): () => void
 * @param name - diagnostic label; duplicate names remain independent.
 * @returns disposer that detaches this surface.
 */
-attachSurface(name: string): () => void
+abstract attachSurface(name: string): () => void
 ```

 Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md)

-Source: [`packages/tasks/tasks/src/index.ts:77`](../../packages/tasks/tasks/src/index.ts)
+Source: [`packages/tasks/tasks/src/index.ts:50`](../../packages/tasks/tasks/src/index.ts)

 ## `ctx.tokenMeter` — `TokenMeterService`

@@ -1853,7 +1887,7 @@ async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>

 Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md)

-Source: [`packages/core/tools/src/index.ts:634`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/index.ts:688`](../../packages/core/tools/src/index.ts)

 ## `ctx.tui` — `TuiExtensionService` (abstract seam)

@@ -2013,15 +2047,6 @@ get(id: WorkspaceId): Workspace | undefined
 */
 list(): Workspace[]

-/**
- * Move one accounted, cwd-validated session to the front of its workspace.
- * Ungrouped sessions and candidates filtered by the header check are
- * no-ops. The owning workspace's relative position never changes.
- * @param sessionId - Session whose activity was observed.
- * @returns resolution after the possible record write.
- */
-async touchSession(sessionId: SessionId): Promise<void>
-
 /**
 * Resolve by canonical directory path without creating or mutating a
 * workspace. A missing path rejects during `realpath`; an existing unowned
@@ -2032,9 +2057,7 @@ async touchSession(sessionId: SessionId): Promise<void>
 async resolveByPath(path: string): Promise<Workspace | undefined>
 ```

-Types: [SessionId](../core-data-structures/core.md)
-
-Source: [`packages/workspace/workspace/src/index.ts:75`](../../packages/workspace/workspace/src/index.ts)
+Source: [`packages/workspace/workspace/src/index.ts:78`](../../packages/workspace/workspace/src/index.ts)

 ## Inherited `ctx` members (cordis core + loader/hmr/timer)