@namzu/sdk 0.1.8 → 0.3.0

package/src/manager/run/persistence.ts

@@ -1,10 +1,11 @@
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
 import { RunDiskStore } from '../../store/run/disk.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
-import type { RunId } from '../../types/ids/index.js'
+import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { AssistantMessage, Message } from '../../types/message/index.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { AgentRun, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
 import { generateEmergencySaveId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
@@ -14,10 +15,18 @@ export class RunPersistence {
 	private runStore: RunDiskStore
 	private pricing?: ModelPricing
 	private log: Logger
+	private readonly _sessionId: SessionId
+	private readonly _threadId: ThreadId
+	private readonly _tenantId: TenantId
+	private readonly _projectId: ProjectId
 
 	constructor(config: RunPersistenceConfig) {
 		this.pricing = config.pricing
 		this.log = config.log
+		this._sessionId = config.sessionId
+		this._threadId = config.threadId
+		this._tenantId = config.tenantId
+		this._projectId = config.projectId
 
 		this.runStore = new RunDiskStore({
 			baseDir: config.outputDir,
@@ -47,6 +56,22 @@ export class RunPersistence {
 		return this.run.id
 	}
 
+	get sessionId(): SessionId {
+		return this._sessionId
+	}
+
+	get threadId(): ThreadId {
+		return this._threadId
+	}
+
+	get tenantId(): TenantId {
+		return this._tenantId
+	}
+
+	get projectId(): ProjectId {
+		return this._projectId
+	}
+
 	get status() {
 		return this.run.status
 	}

package/src/manager/thread/__tests__/lifecycle.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it } from 'vitest'
+import { ThreadClosedError, ThreadNotEmptyError } from '../../../session/errors.js'
+import type { ActorRef } from '../../../session/hierarchy/actor.js'
+import { InMemorySessionStore } from '../../../store/session/memory.js'
+import { InMemoryThreadStore } from '../../../store/thread/memory.js'
+import type { AgentId, TenantId, UserId } from '../../../types/ids/index.js'
+import type { ThreadId } from '../../../types/session/ids.js'
+import { ThreadManager } from '../lifecycle.js'
+
+const MISSING_THREAD_ID = 'thd_missing' as ThreadId
+
+const tenantA = 'tnt_alpha' as TenantId
+const tenantB = 'tnt_beta' as TenantId
+
+function userActor(tenantId: TenantId): ActorRef {
+	return { kind: 'user', userId: 'usr_a' as UserId, tenantId }
+}
+
+function agentActor(tenantId: TenantId): ActorRef {
+	return { kind: 'agent', agentId: 'agt_a' as AgentId, tenantId }
+}
+
+async function harness(tenantId: TenantId = tenantA) {
+	const threadStore = new InMemoryThreadStore()
+	const sessionStore = new InMemorySessionStore()
+	const project = await sessionStore.createProject({ tenantId, name: 'p1' }, tenantId)
+	const thread = await threadStore.createThread({ projectId: project.id, title: 't' }, tenantId)
+	const manager = new ThreadManager({ threadStore, sessionStore })
+	return { threadStore, sessionStore, project, thread, manager }
+}
+
+describe('ThreadManager', () => {
+	describe('requireOpen', () => {
+		it('returns the thread when open', async () => {
+			const { thread, manager } = await harness()
+			await expect(manager.requireOpen(thread.id, tenantA)).resolves.toMatchObject({
+				id: thread.id,
+				status: 'open',
+			})
+		})
+
+		it('throws ThreadClosedError when archived', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			await expect(manager.requireOpen(thread.id, tenantA)).rejects.toBeInstanceOf(
+				ThreadClosedError,
+			)
+		})
+
+		it('throws when the thread does not exist', async () => {
+			const { manager } = await harness()
+			await expect(manager.requireOpen(MISSING_THREAD_ID, tenantA)).rejects.toThrow(/not found/)
+		})
+	})
+
+	describe('archive', () => {
+		it('flips status to archived and bumps ownerVersion', async () => {
+			const { thread, manager } = await harness()
+			const archived = await manager.archive(thread.id, tenantA)
+			expect(archived.status).toBe('archived')
+			expect(archived.ownerVersion).toBe(thread.ownerVersion + 1)
+		})
+
+		it('is idempotent on an already-archived thread (no store write)', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			const before = await threadStore.getThread(thread.id, tenantA)
+
+			const result = await manager.archive(thread.id, tenantA)
+			expect(result.status).toBe('archived')
+			// Re-archival must NOT advance ownerVersion — the store would have
+			// rejected a second updateThread as stale anyway; we assert the
+			// short-circuit path held instead.
+			expect(result.ownerVersion).toBe(before?.ownerVersion)
+		})
+
+		it('throws when the thread does not exist', async () => {
+			const { manager } = await harness()
+			await expect(manager.archive(MISSING_THREAD_ID, tenantA)).rejects.toThrow(/not found/)
+		})
+
+		it('rejects with ThreadNotEmptyError when a session is active', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			const session = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...session, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					threadId: thread.id,
+					tenantId: tenantA,
+					op: 'archive',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: session.id, status: 'active' }],
+				},
+			})
+		})
+
+		it('defensive re-check: already-archived thread with a smuggled active session still rejects', async () => {
+			// Flip the thread to archived directly (bypassing manager.archive so
+			// no check runs), then attach an active session via direct store
+			// mutation. A subsequent manager.archive() must surface the offender
+			// as ThreadNotEmptyError, not short-circuit as "already archived".
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			await threadStore.updateThread({ ...thread, status: 'archived' }, tenantA)
+			const smuggled = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...smuggled, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					op: 'archive',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: smuggled.id, status: 'active' }],
+				},
+			})
+		})
+
+		it.each(['locked', 'awaiting_hitl', 'awaiting_merge'] as const)(
+			'rejects when a session is %s',
+			async (status) => {
+				const { thread, project, manager, sessionStore } = await harness()
+				const session = await sessionStore.createSession(
+					{
+						threadId: thread.id,
+						projectId: project.id,
+						currentActor: userActor(tenantA),
+					},
+					tenantA,
+				)
+				await sessionStore.updateSession({ ...session, status }, tenantA)
+
+				await expect(manager.archive(thread.id, tenantA)).rejects.toBeInstanceOf(
+					ThreadNotEmptyError,
+				)
+			},
+		)
+
+		it('allows archival when every session is quiescent (idle / failed / archived)', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			// `createSession` defaults to `idle`; force the others via updateSession.
+			await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			const sFailed = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: agentActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...sFailed, status: 'failed' }, tenantA)
+
+			const archived = await manager.archive(thread.id, tenantA)
+			expect(archived.status).toBe('archived')
+		})
+
+		it('ignores sessions attached to a sibling thread', async () => {
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			const other = await threadStore.createThread(
+				{ projectId: project.id, title: 'other' },
+				tenantA,
+			)
+			// Active session under the OTHER thread must not block archival of
+			// `thread`.
+			const otherSession = await sessionStore.createSession(
+				{
+					threadId: other.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await sessionStore.updateSession({ ...otherSession, status: 'active' }, tenantA)
+
+			await expect(manager.archive(thread.id, tenantA)).resolves.toMatchObject({
+				status: 'archived',
+			})
+		})
+
+		it('does not leak cross-tenant sessions into the precondition', async () => {
+			// Shared stores across tenants (production shape). A session with
+			// the same threadId string under tenantB must not block archival
+			// of tenantA's thread.
+			const threadStore = new InMemoryThreadStore()
+			const sessionStore = new InMemorySessionStore()
+			const manager = new ThreadManager({ threadStore, sessionStore })
+
+			const pA = await sessionStore.createProject({ tenantId: tenantA, name: 'pa' }, tenantA)
+			const pB = await sessionStore.createProject({ tenantId: tenantB, name: 'pb' }, tenantB)
+			const tA = await threadStore.createThread({ projectId: pA.id, title: 'ta' }, tenantA)
+
+			// Cross-tenant session with the same threadId string as tA.
+			const bSession = await sessionStore.createSession(
+				{ threadId: tA.id, projectId: pB.id, currentActor: userActor(tenantB) },
+				tenantB,
+			)
+			await sessionStore.updateSession({ ...bSession, status: 'active' }, tenantB)
+
+			await expect(manager.archive(tA.id, tenantA)).resolves.toMatchObject({
+				status: 'archived',
+			})
+		})
+	})
+
+	describe('delete', () => {
+		it('deletes an empty thread', async () => {
+			const { thread, manager, threadStore } = await harness()
+			await manager.delete(thread.id, tenantA)
+			expect(await threadStore.getThread(thread.id, tenantA)).toBeNull()
+		})
+
+		it('rejects with ThreadNotEmptyError when any session references the thread', async () => {
+			const { thread, project, manager, sessionStore } = await harness()
+			const session = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			// Idle — allowed under archive, still blocks delete.
+			await expect(manager.delete(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					threadId: thread.id,
+					tenantId: tenantA,
+					op: 'delete',
+					totalBlockingSessions: 1,
+					blockingSessions: [{ sessionId: session.id, status: 'idle' }],
+				},
+			})
+		})
+
+		it('detects orphaned sessions referencing a missing thread', async () => {
+			// Thread record is destroyed via the store directly, but a session
+			// still carries its threadId. Manager.delete must reject rather
+			// than silently succeed on the "thread is already gone" short-cut
+			// (the session scan runs unconditionally).
+			const { thread, project, manager, sessionStore, threadStore } = await harness()
+			const orphan = await sessionStore.createSession(
+				{
+					threadId: thread.id,
+					projectId: project.id,
+					currentActor: userActor(tenantA),
+				},
+				tenantA,
+			)
+			await threadStore.deleteThread(thread.id, tenantA)
+
+			await expect(manager.delete(thread.id, tenantA)).rejects.toMatchObject({
+				name: 'ThreadNotEmptyError',
+				details: {
+					op: 'delete',
+					blockingSessions: [{ sessionId: orphan.id, status: 'idle' }],
+				},
+			})
+		})
+
+		it('is idempotent for an absent thread with no orphans', async () => {
+			const { manager } = await harness()
+			await expect(manager.delete(MISSING_THREAD_ID, tenantA)).resolves.toBeUndefined()
+		})
+	})
+})

package/src/manager/thread/lifecycle.ts

@@ -0,0 +1,217 @@
+/**
+ * ThreadManager — thin orchestrator over {@link ThreadStore} and
+ * {@link SessionStore}.
+ *
+ * Owns user-facing lifecycle operations on the Thread topic layer plus the
+ * archive-gate contract enforced at session-creation ingress sites.
+ *
+ * Phase 2.6 wired `ThreadManager.requireOpen` into three ingress paths:
+ *   - {@link AgentManager.provisionSpawn} (child session creation)
+ *   - `executeSingleHandoff` (recipient session creation)
+ *   - `executeBroadcastHandoff` (N recipient sessions per fan-out)
+ * Those call sites depend on this manager, so the one-method indirection
+ * stopped being "structural overhead" the moment archive/delete needed the
+ * session-presence cross-check anyway.
+ *
+ * Archive + delete require cross-store preconditions (session-presence
+ * checks) — enforced here where both stores are in scope. The stores
+ * themselves stay unaware of each other's layout (Convention #0), which is
+ * why the gate lives at the manager layer rather than as a universal store
+ * interceptor (see `archive` JSDoc for the direct-store-bypass boundary).
+ */
+
+import {
+	THREAD_NOT_EMPTY_SAMPLE_LIMIT,
+	ThreadClosedError,
+	ThreadNotEmptyError,
+} from '../../session/errors.js'
+import type { Session, SessionStatus } from '../../session/hierarchy/session.js'
+import type { Thread } from '../../session/hierarchy/thread.js'
+import type { TenantId } from '../../types/ids/index.js'
+import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { SessionStore } from '../../types/session/store.js'
+import type { CreateThreadParams, ThreadStore } from '../../types/thread/store.js'
+
+export interface ThreadManagerDeps {
+	readonly threadStore: ThreadStore
+	readonly sessionStore: SessionStore
+}
+
+/**
+ * Session statuses that block Thread archival. A session in any of these
+ * states has live work in-flight (mid-run, mid-handoff, blocked on human
+ * input, or orchestrating a broadcast merge) — freezing the Thread while any
+ * of them are active would strand resumable work.
+ *
+ * `idle`, `failed`, and `archived` are archival-compatible: they are
+ * quiescent or already-terminal, so a newly-frozen Thread can safely contain
+ * them. This list mirrors the `SessionStatus` discriminants that represent
+ * "not-yet-done" work (session-hierarchy.md §5.1).
+ */
+const ARCHIVAL_BLOCKING_STATUSES: ReadonlySet<SessionStatus> = new Set([
+	'active',
+	'locked',
+	'awaiting_hitl',
+	'awaiting_merge',
+])
+
+export class ThreadManager {
+	private readonly deps: ThreadManagerDeps
+
+	constructor(deps: ThreadManagerDeps) {
+		this.deps = deps
+	}
+
+	/** Persist a new Thread. Thin passthrough for uniformity at the manager surface. */
+	create(params: CreateThreadParams, tenantId: TenantId): Promise<Thread> {
+		return this.deps.threadStore.createThread(params, tenantId)
+	}
+
+	/** Read a Thread by id; returns `null` when absent for the tenant. */
+	get(threadId: ThreadId, tenantId: TenantId): Promise<Thread | null> {
+		return this.deps.threadStore.getThread(threadId, tenantId)
+	}
+
+	/**
+	 * CAS update on a Thread. Propagates {@link import('../../session/errors.js').StaleThreadError}
+	 * from the store on `ownerVersion` mismatch — callers re-read, re-apply,
+	 * and retry.
+	 */
+	update(thread: Thread, tenantId: TenantId): Promise<void> {
+		return this.deps.threadStore.updateThread(thread, tenantId)
+	}
+
+	/** List Threads under a Project, ordered by `createdAt` ascending. */
+	list(projectId: ProjectId, tenantId: TenantId): Promise<readonly Thread[]> {
+		return this.deps.threadStore.listThreads(projectId, tenantId)
+	}
+
+	/**
+	 * Load a Thread and assert it is in `'open'` state. Used by the spawn path
+	 * as a precondition — a SubSession cannot be created under an archived
+	 * Thread. Throws on absence and on archival; returns the loaded Thread on
+	 * success so callers can avoid the second round-trip.
+	 *
+	 * Convention #5: deny-by-default. A missing Thread is a hard error, not a
+	 * silent "assume archived".
+	 */
+	async requireOpen(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
+		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!thread) {
+			throw new Error(`Thread ${threadId} not found`)
+		}
+		if (thread.status === 'archived') {
+			throw new ThreadClosedError({ threadId, op: 'require-open' })
+		}
+		return thread
+	}
+
+	/**
+	 * Flip a Thread to `'archived'` via CAS on {@link Thread.ownerVersion}.
+	 *
+	 * Preconditions (checked in order):
+	 *   1. Thread exists for the tenant (throws on absence).
+	 *   2. No attached Session is in a non-terminal state (see
+	 *      {@link ARCHIVAL_BLOCKING_STATUSES}). The presence check runs
+	 *      **before** the idempotent-archive short-circuit so that an already
+	 *      archived thread harboring a live session still surfaces as
+	 *      {@link ThreadNotEmptyError} rather than a silent success.
+	 *   3. If the thread is already `'archived'` the method short-circuits
+	 *      without an `updateThread` write (idempotent re-archival). The
+	 *      returned record reflects the current persisted state.
+	 *
+	 * On a fresh archive transition the underlying
+	 * {@link ThreadStore.updateThread} call commits with `ownerVersion + 1`.
+	 * A {@link import('../../session/errors.js').StaleThreadError} from a
+	 * concurrent writer propagates unchanged — the caller is expected to
+	 * re-read + retry (mirrors the `updateThread` contract).
+	 *
+	 * Gate scope (Phase 2.6): `ThreadManager.requireOpen` is wired into
+	 * `AgentManager.provisionSpawn` and both handoff flows, so the production
+	 * ingress paths cannot attach new sessions under an archived thread.
+	 * `SessionStore.createSession` / `updateSession` remain public and
+	 * ungated at the store layer — a direct caller can still mutate a
+	 * session after archival (the store has no `ThreadStore` handle by
+	 * design; cross-store awareness lives in the manager). The defensive
+	 * re-check above catches a smuggled live session on a subsequent
+	 * archive call, but does not prevent the direct-store write from
+	 * landing. That's an acceptable boundary — kernel callers must go
+	 * through the ingress paths; direct store consumers are out of scope
+	 * for the archive invariant.
+	 */
+	async archive(threadId: ThreadId, tenantId: TenantId): Promise<Thread> {
+		const thread = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!thread) {
+			throw new Error(`Thread ${threadId} not found`)
+		}
+
+		// Always enforce the blocking-session invariant — even on re-archival.
+		// If the thread is already archived but somehow gained a live session
+		// (direct store mutation, concurrent spawn before a write-barrier
+		// existed), surfacing that via ThreadNotEmptyError is more useful to
+		// operators than a silent idempotent success.
+		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
+		const blocking = sessions.filter((s) => ARCHIVAL_BLOCKING_STATUSES.has(s.status))
+		if (blocking.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId,
+				tenantId,
+				op: 'archive',
+				blockingSessions: summarizeBlocking(blocking),
+				totalBlockingSessions: blocking.length,
+			})
+		}
+
+		if (thread.status === 'archived') {
+			// Idempotent: already archived, no live sessions attached. Skip the
+			// write (updateThread would still bump ownerVersion for no semantic
+			// change).
+			return thread
+		}
+
+		const next: Thread = { ...thread, status: 'archived' }
+		await this.deps.threadStore.updateThread(next, tenantId)
+		// updateThread advances ownerVersion + updatedAt; re-read so the returned
+		// record reflects the persisted state (callers rely on version monotonicity).
+		const reloaded = await this.deps.threadStore.getThread(threadId, tenantId)
+		if (!reloaded) {
+			throw new Error(`Thread ${threadId} vanished between archive and read-back`)
+		}
+		return reloaded
+	}
+
+	/**
+	 * Hard-delete a Thread record. Rejects with {@link ThreadNotEmptyError}
+	 * (`op: 'delete'`) when ANY Session still references the Thread —
+	 * deletion is stricter than archival, which tolerates quiescent sessions.
+	 * Callers must first delete or archive-and-tombstone every attached
+	 * session (via {@link SessionStore.deleteSession}) before invoking.
+	 *
+	 * The session scan runs unconditionally, so orphaned sessions pointing at
+	 * a missing thread are still detected and reject the delete. Idempotent
+	 * for genuinely absent threads (no sessions, no thread record) — missing
+	 * thread + empty session list is a no-op at the store layer. Convention
+	 * #5: deny-by-default; no implicit cascade into SessionStore.
+	 */
+	async delete(threadId: ThreadId, tenantId: TenantId): Promise<void> {
+		const sessions = await this.deps.sessionStore.listSessions(threadId, tenantId)
+		if (sessions.length > 0) {
+			throw new ThreadNotEmptyError({
+				threadId,
+				tenantId,
+				op: 'delete',
+				blockingSessions: summarizeBlocking(sessions),
+				totalBlockingSessions: sessions.length,
+			})
+		}
+		await this.deps.threadStore.deleteThread(threadId, tenantId)
+	}
+}
+
+function summarizeBlocking(
+	sessions: readonly Session[],
+): ReadonlyArray<{ sessionId: Session['id']; status: SessionStatus }> {
+	return sessions
+		.slice(0, THREAD_NOT_EMPTY_SAMPLE_LIMIT)
+		.map((s) => ({ sessionId: s.id, status: s.status }))
+}

package/src/rag/retriever.ts

@@ -57,11 +57,11 @@ export class DefaultRetriever implements Retriever {
 	}
 
 	private expandQuery(query: RetrievalQuery): string {
-		if (!query.threadMessages || query.threadMessages.length === 0) {
+		if (!query.recentMessages || query.recentMessages.length === 0) {
 			return query.text
 		}
 
-		const recentContext = query.threadMessages.slice(-3).join(' ')
+		const recentContext = query.recentMessages.slice(-3).join(' ')
 		return `${query.text}\n\nContext: ${recentContext}`
 	}
 

package/src/run/reporter.ts

@@ -194,6 +194,34 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'subsession_spawned':
+				log.debug('Sub-session spawned', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					depth: event.lineage.depth,
+				})
+				break
+
+			case 'subsession_messaged':
+				log.debug('Sub-session message', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					messageId: event.messageId,
+					depth: event.lineage.depth,
+				})
+				break
+
+			case 'subsession_idled':
+				log.debug('Sub-session idled', {
+					runId: event.runId,
+					subSessionId: event.subSessionId,
+					parentSessionId: event.parentSessionId,
+					depth: event.lineage.depth,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)