2 commits

Author	SHA1	Message	Date
liruifengv	eaa3969dd3	feat(kap-server): add page mode, updated_before, and batch archive/restore to v2 sessions (#2983) ... * feat(kap-server): add page-number mode and total to GET /api/v2/sessions The v2 session list gains a stateless 1-based `page` parameter beside the opaque page_token cursor for admin-style lists that jump arbitrarily: each request stays a full independent snapshot, no token is minted, and `page` + `page_token` together fail 40001. Every response now carries `total` (the filtered/sorted set size) in both pagination modes. * feat(kap-server): add meta.updated_before filter to GET /api/v2/sessions Symmetric with meta.updated_after (inclusive boundary, Unix ms), applied at the edge over the drained set and bound into the page_token query fingerprint like every other condition. * feat(kap-server): add POST /api/v2/sessions:archive and :restore batch endpoints Batch archive/restore for session-management views: { ids } (non-empty, ≤5000 unique after dedup) answers per-item results in input order with succeeded/failed counts — only a body validation failure fails the whole request, and an unknown id folds into its own item as 40401. The live/cold split keeps the batch cheap: a session with a live handle goes through the full ISessionLifecycleService chain (agents drain, scope teardown, mirror drain), while a cold session is never materialized — the new setColdSessionArchived helper in agent-core-v2 patches the persisted state.json (archived/archivedAt, updatedAt preserved, mirroring setArchived's touchUpdatedAt: false semantics), mirrors the flipped summary into the read-model queue, and republishes the same event.session.archived bus event the live lifecycle emits (:restore publishes nothing, matching the live restore). Hot items run with bounded concurrency and the batch ends with one shared ISessionIndexMirror.drain(). * docs(server-api): document v2 sessions page mode, total, updated_before, and batch archive/restore * fix(kap-server): deep-import workspace lifecycle symbols in the v2 sessions route CI's tsgo/rolldown (Linux) fail to bind liveHandlerForSession and IWorkspaceLifecycleService through the agent-core-v2 package-root barrel even though it re-exports them; the same files use the established deep-import pattern already used for the git domain. * fix(kap-server): inline the live-handler lookup in the batch route The previous deep imports still fail to resolve on CI's Linux toolchain (tsgo TS2307, rolldown MISSING_EXPORT) while every other module path from the same package binds fine. Keep the route self-contained: the hot-path lookup is a five-line loop over IWorkspaceLifecycleService's handlers (mirrors agent-core-v2's liveHandlerForSession), and the tests assert non-materialization behaviorally via the live map instead of importing the same two symbols for spies. * fix(kap-server): drive the batch hot path through getLiveSessionById The phantom only hits the workspaceLifecycle-group symbols in these two files on CI's Linux toolchain; getLiveSessionById is observed to bind fine there. It returns the session's live scope directly (no resume), which is exactly what the batch hot path needs. * refactor(kap-server): move the batch live/cold split into agent-core-v2 setSessionArchivedBatch owns the split next to the cold patch: live sessions go through the full lifecycle chain via the workspace handler accessor (the v1-proven resolution path), cold sessions through the direct write. The route becomes a thin wire-code adapter, and the batch tests assert the live chain behaviorally (disposal, events, index) instead of spying through scope accessors. * fix(agent-core-v2): import sessionLookup relatively from coldSessionArchive The '#/app/workspaceLifecycle/*' specifier resolves from src/ and src/app/* files on CI's Linux toolchain but not from src/workspace/sessionLifecycle/ (tsgo TS2307, rolldown follows); a relative import bypasses the package-imports mapping. * fix(agent-core-v2): migrate the batch hot path to ISessionManager Main's workspace/session DI refactor removed the workspaceLifecycle lookup modules; the live branch now goes through the App-level ISessionManager (the same entry the v1 action route uses post-refactor) with getLiveSessionById from the new sessionManager lookup. * feat(kap-server): add the id,archived item projection to GET /api/v2/sessions fields=id,archived trims each item to { id, archived } for select-all-matching flows (the session admin page's Gmail-style select-all). Only that projection gets the relaxed page_size ceiling (10000); unknown fields, non-pair subsets, and include=git combinations are 40001, and the projection binds into the page_token fingerprint so shapes never flip mid-pagination. * fix(agent-core-v2): serialize the batch cold write against in-flight resumes Codex review on #2983: while a resume is in flight the live registry hides the handle, so the batch route could classify the session as cold and its direct write would race the materializing metadata service (its stale in-memory document wins the next write, silently un-archiving the session after the endpoint reported success). The batch now settles the resume first: SessionManager registers the whole resume promise synchronously at the App level (controllerForSession is async, so the controller's own resuming map learns about it a few microtasks late) and whenResumeSettled awaits it before classification — a settled resume lands the item on the live chain, a failed one falls back to the cold path. Also folds the module header down to the package's external-role comment convention. * fix(agent-core-v2): publish SessionArchived as an Event2 class in cold archive * fix(agent-core-v2): serialize batch archive/restore with session lifecycle transitions * fix(agent-core-v2): serialize session delete with the lifecycle chain * fix(agent-core-v2): mirror the persisted metadata on cold archive, not the index summary * docs(agent-core-v2): bring sessionManager comments and new tests to package conventions * fix(agent-core-v2): normalize legacy session metadata before the cold archive write * fix(kap-server): serialize the v1 single-session archive with the lifecycle chain * chore: drop changesets for internal-only protocol work * fix(agent-core-v2): encode cold-archived metadata for v1 readers * fix(agent-core-v2): serialize fork and createChild with the source session's chain * refactor(agent-core-v2): chain every session lifecycle method and hand batch sections unguarded ops * fix(agent-core-v2): propagate failed resumes to the next settle * fix(agent-core-v2): roll back the unannounced handle when a resume fails mid-materialization * fix(agent-core-v2): read and migrate the legacy session-meta location on cold archive * fix(agent-core-v2): serialize explicit-id session creation with the lifecycle chain create() with a caller-supplied sessionId bypassed the per-session chain, so a concurrent batch archive could classify the half-created session as cold and write archived state that the live metadata service later overwrites. Creation now queues on the target id's chain whenever an explicit id is present. Also type the resume-failure maps as Error and normalize at the catch site, satisfying only-throw-error. * style(kap-server): strip comments from the session routes per the no-comments convention * fix(agent-core-v2): serialize explicit fork and child target ids on the lifecycle chain fork() and createChild() with a newSessionId locked only the source id, so a batch archive of the target could slip into the creation window: the index already knows the half-created session, the batch writes archived state to its document, and the fork's in-memory metadata later overwrites it. Both operations now acquire the deduped, sorted key set so multi-key sections always take locks in one deterministic order.	2026-08-18 13:57:37 +08:00
Haozhe	dc8db90cdd	docs(server): add local server guide and API reference (#2839) ... * docs(server): add local server guide and API reference * docs(server): qualify binary endpoint HTTP semantics	2026-08-12 12:29:09 +08:00