@namzu/sdk 0.1.7 → 0.2.0

package/src/store/session/index.ts

@@ -0,0 +1,14 @@
+// Sub-barrel for the session-scoped persistence module (Convention #4).
+//
+// `SessionStore` replaces the legacy `ConversationStore`; messages are scoped
+// to a `SessionId` (not a bare thread) and every accessor carries explicit
+// `TenantId` per session-hierarchy.md §12.1. Concrete implementations live
+// in sibling files; re-export them here so consumers import via
+// `../store/session/index.js`.
+
+export { InMemorySessionStore } from './memory.js'
+export { DiskSessionStore } from './disk.js'
+export type { DiskSessionStoreConfig } from './disk.js'
+export type { SessionMessage } from './messages.js'
+export { getAncestry, getChildren, orderChildren } from './linkage.js'
+export type { LinkageView } from './linkage.js'

package/src/store/session/linkage.ts

@@ -0,0 +1,80 @@
+/**
+ * Linkage helpers for {@link SessionStore} — pure functions over raw store
+ * maps so they can be reused by both {@link InMemorySessionStore} and
+ * {@link DiskSessionStore}.
+ *
+ * See session-hierarchy.md §10.4 (Parent-Child Linkage) and §14.3 (drill
+ * primitive). Ancestry walks are cycle-guarded via visited-set; detection
+ * surfaces as {@link AncestryCycleError}.
+ */
+
+import { AncestryCycleError } from '../../session/errors.js'
+import type { SubSession } from '../../session/hierarchy/sub-session.js'
+import type { SessionId } from '../../types/ids/index.js'
+import type { SubSessionId } from '../../types/session/ids.js'
+
+/**
+ * Read shape required by the pure linkage helpers. Both in-memory and disk
+ * stores project their internal state into this view before delegating.
+ */
+export interface LinkageView {
+	findChildSubSessions(parentSessionId: SessionId): readonly SubSession[]
+	findParentSubSession(childSessionId: SessionId): SubSession | null
+}
+
+/**
+ * Returns direct children of `sessionId` (one level). Pure over `view`.
+ */
+export function getChildren(view: LinkageView, sessionId: SessionId): readonly SubSession[] {
+	return view.findChildSubSessions(sessionId)
+}
+
+/**
+ * Walks parent sub-session links and returns the session id chain from root
+ * to `sessionId` inclusive. Guards against cycles via a visited-set — in
+ * a healthy store the invariant holds and the guard never fires; a cycle
+ * indicates corruption (session-hierarchy.md §4.5 enforces acyclicity on
+ * write).
+ */
+export function getAncestry(view: LinkageView, sessionId: SessionId): readonly SessionId[] {
+	const visited = new Set<SessionId>()
+	const chain: SessionId[] = []
+	let cursor: SessionId | null = sessionId
+
+	while (cursor !== null) {
+		if (visited.has(cursor)) {
+			throw new AncestryCycleError({
+				sessionId,
+				cyclePath: [...chain, cursor],
+			})
+		}
+		visited.add(cursor)
+		chain.push(cursor)
+
+		const parentEdge: SubSession | null = view.findParentSubSession(cursor)
+		cursor = parentEdge ? parentEdge.parentSessionId : null
+	}
+
+	// Reverse so the result is root-to-self, matching session-hierarchy.md §14.3.
+	return chain.reverse()
+}
+
+/**
+ * Pairs {@link SubSession} children with a stable order (spawnedAt ascending,
+ * then id as a deterministic tiebreaker). Callers that need a different
+ * ordering can re-sort.
+ */
+export function orderChildren(children: readonly SubSession[]): readonly SubSession[] {
+	return [...children].sort((a, b) => {
+		const ta = a.spawnedAt.getTime()
+		const tb = b.spawnedAt.getTime()
+		if (ta !== tb) return ta - tb
+		return compareSubSessionId(a.id, b.id)
+	})
+}
+
+function compareSubSessionId(a: SubSessionId, b: SubSessionId): number {
+	if (a < b) return -1
+	if (a > b) return 1
+	return 0
+}

package/src/store/session/memory.ts

@@ -0,0 +1,400 @@
+/**
+ * InMemorySessionStore — reference in-memory implementation of
+ * {@link SessionStore}.
+ *
+ * Every accessor takes explicit {@link TenantId} (Convention #17). Any
+ * accessor called with a tenantId that does not match the resource's owning
+ * tenant throws {@link TenantIsolationError} — there is no fallback
+ * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
+ */
+
+import { TenantIsolationError } from '../../session/errors.js'
+import type { Project } from '../../session/hierarchy/project.js'
+import type { Session } from '../../session/hierarchy/session.js'
+import type { SubSession } from '../../session/hierarchy/sub-session.js'
+import { SessionAlreadySummarizedError } from '../../session/summary/ref.js'
+import type { SessionSummaryRef } from '../../session/summary/ref.js'
+import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+import type { ProjectId, SubSessionId } from '../../types/session/ids.js'
+import type {
+	CreateProjectParams,
+	CreateSessionParams,
+	CreateSubSessionParams,
+	SessionStore,
+	SessionView,
+} from '../../types/session/store.js'
+import {
+	generateMessageId,
+	generateProjectId,
+	generateSessionId,
+	generateSubSessionId,
+} from '../../utils/id.js'
+import { getAncestry, getChildren, orderChildren } from './linkage.js'
+import type { LinkageView } from './linkage.js'
+import type { SessionMessage } from './messages.js'
+
+interface ProjectRecord {
+	tenantId: TenantId
+	project: Project
+}
+
+interface SessionRecord {
+	tenantId: TenantId
+	session: Session
+}
+
+interface SubSessionRecord {
+	tenantId: TenantId
+	subSession: SubSession
+}
+
+interface SummaryRecord {
+	tenantId: TenantId
+	summary: SessionSummaryRef
+}
+
+/**
+ * Non-terminal statuses from which {@link InMemorySessionStore.recordSummary}
+ * flips the owning session to `'idle'` as part of the atomic materialize +
+ * transition contract (session-hierarchy.md §8.1). Other statuses — already
+ * terminal or awaiting HITL — are left untouched.
+ */
+const SUMMARY_TERMINAL_FLIP_STATUSES: ReadonlySet<Session['status']> = new Set([
+	'active',
+	'locked',
+	'awaiting_merge',
+])
+
+export class InMemorySessionStore implements SessionStore {
+	private readonly projects = new Map<ProjectId, ProjectRecord>()
+	private readonly sessions = new Map<SessionId, SessionRecord>()
+	private readonly subSessions = new Map<SubSessionId, SubSessionRecord>()
+	private readonly messages = new Map<SessionId, SessionMessage[]>()
+	private readonly summaries = new Map<SessionId, SummaryRecord>()
+
+	// Project CRUD ------------------------------------------------------------
+
+	async createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project> {
+		if (params.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `project(name=${params.name})`,
+			})
+		}
+		const now = new Date()
+		const project: Project = {
+			id: generateProjectId(),
+			tenantId,
+			name: params.name,
+			config: {
+				maxDelegationDepth: 4,
+				maxDelegationWidth: 8,
+				maxInterventionDepth: 10,
+			},
+			createdAt: now,
+			updatedAt: now,
+		}
+		this.projects.set(project.id, { tenantId, project })
+		return project
+	}
+
+	async getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null> {
+		const record = this.projects.get(projectId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `project(${projectId})`)
+		return record.project
+	}
+
+	// Session CRUD ------------------------------------------------------------
+
+	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
+		const projectRecord = this.projects.get(params.projectId)
+		if (!projectRecord) {
+			throw new Error(`Project ${params.projectId} not found`)
+		}
+		this.assertTenant(projectRecord.tenantId, tenantId, `project(${params.projectId})`)
+
+		const now = new Date()
+		const session: Session = {
+			id: generateSessionId(),
+			projectId: params.projectId,
+			tenantId,
+			status: 'idle',
+			currentActor: params.currentActor,
+			previousActors: [],
+			workspaceId: null,
+			ownerVersion: 0,
+			createdAt: now,
+			updatedAt: now,
+		}
+		this.sessions.set(session.id, { tenantId, session })
+		return session
+	}
+
+	async getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+		return record.session
+	}
+
+	async updateSession(session: Session, tenantId: TenantId): Promise<void> {
+		const record = this.sessions.get(session.id)
+		if (!record) {
+			throw new Error(`Session ${session.id} not found`)
+		}
+		this.assertTenant(record.tenantId, tenantId, `session(${session.id})`)
+		if (session.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `session(${session.id}) payload`,
+			})
+		}
+		this.sessions.set(session.id, { tenantId, session: { ...session, updatedAt: new Date() } })
+	}
+
+	async deleteSession(sessionId: SessionId, tenantId: TenantId): Promise<void> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return // Idempotent: missing = no-op.
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+
+		// Policy: reject if sub-sessions still attach to this session (either as
+		// parent or child). Callers must delete children first — Convention #5
+		// deny-by-default; no implicit cascade.
+		for (const subRecord of this.subSessions.values()) {
+			const { subSession } = subRecord
+			if (subSession.parentSessionId === sessionId || subSession.childSessionId === sessionId) {
+				throw new Error(
+					`Session ${sessionId} has attached sub-sessions; delete them before deleting the session`,
+				)
+			}
+		}
+
+		this.sessions.delete(sessionId)
+		this.messages.delete(sessionId)
+		this.summaries.delete(sessionId)
+	}
+
+	// SubSession CRUD ---------------------------------------------------------
+
+	async createSubSession(params: CreateSubSessionParams, tenantId: TenantId): Promise<SubSession> {
+		const parentRecord = this.sessions.get(params.parentSessionId)
+		if (!parentRecord) {
+			throw new Error(`Parent session ${params.parentSessionId} not found`)
+		}
+		this.assertTenant(parentRecord.tenantId, tenantId, `session(${params.parentSessionId})`)
+
+		const childRecord = this.sessions.get(params.childSessionId)
+		if (!childRecord) {
+			throw new Error(`Child session ${params.childSessionId} not found`)
+		}
+		this.assertTenant(childRecord.tenantId, tenantId, `session(${params.childSessionId})`)
+
+		const now = new Date()
+		const subSession: SubSession = {
+			id: generateSubSessionId(),
+			parentSessionId: params.parentSessionId,
+			childSessionId: params.childSessionId,
+			kind: params.kind,
+			status: 'pending',
+			spawnedBy: params.spawnedBy,
+			spawnedAt: now,
+			failureMode: params.failureMode ?? 'delegate',
+			completionMode: params.completionMode ?? 'summary_ref',
+			workspaceId: null,
+			updatedAt: now,
+		}
+		this.subSessions.set(subSession.id, { tenantId, subSession })
+		return subSession
+	}
+
+	async getSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<SubSession | null> {
+		const record = this.subSessions.get(subSessionId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `sub-session(${subSessionId})`)
+		return record.subSession
+	}
+
+	async updateSubSession(subSession: SubSession, tenantId: TenantId): Promise<void> {
+		const record = this.subSessions.get(subSession.id)
+		if (!record) {
+			throw new Error(`SubSession ${subSession.id} not found`)
+		}
+		this.assertTenant(record.tenantId, tenantId, `sub-session(${subSession.id})`)
+		this.subSessions.set(subSession.id, {
+			tenantId,
+			subSession: { ...subSession, updatedAt: new Date() },
+		})
+	}
+
+	async deleteSubSession(subSessionId: SubSessionId, tenantId: TenantId): Promise<void> {
+		const record = this.subSessions.get(subSessionId)
+		if (!record) return // Idempotent: missing = no-op.
+		this.assertTenant(record.tenantId, tenantId, `sub-session(${subSessionId})`)
+		this.subSessions.delete(subSessionId)
+	}
+
+	// Messages ----------------------------------------------------------------
+
+	async appendMessage(
+		sessionId: SessionId,
+		message: Message,
+		tenantId: TenantId,
+	): Promise<MessageId> {
+		const record = this.sessions.get(sessionId)
+		if (!record) {
+			throw new Error(`Session ${sessionId} not found`)
+		}
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+
+		const id = generateMessageId()
+		const entry: SessionMessage = {
+			id,
+			sessionId,
+			tenantId,
+			message,
+			at: new Date(),
+		}
+		const existing = this.messages.get(sessionId)
+		if (existing) {
+			existing.push(entry)
+		} else {
+			this.messages.set(sessionId, [entry])
+		}
+		return id
+	}
+
+	async loadMessages(sessionId: SessionId, tenantId: TenantId): Promise<readonly Message[]> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return []
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+		const entries = this.messages.get(sessionId) ?? []
+		return entries.map((e) => e.message)
+	}
+
+	async loadSessionMessages(
+		sessionId: SessionId,
+		tenantId: TenantId,
+	): Promise<readonly SessionMessage[]> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return []
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+		const entries = this.messages.get(sessionId) ?? []
+		// Return a shallow copy so callers cannot mutate the internal log.
+		return entries.map((e) => ({ ...e }))
+	}
+
+	// Linkage -----------------------------------------------------------------
+
+	async getChildren(sessionId: SessionId, tenantId: TenantId): Promise<readonly SubSession[]> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return []
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+		return orderChildren(getChildren(this.linkageView(tenantId), sessionId))
+	}
+
+	async getAncestry(sessionId: SessionId, tenantId: TenantId): Promise<readonly SessionId[]> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return []
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+		return getAncestry(this.linkageView(tenantId), sessionId)
+	}
+
+	async drill(sessionId: SessionId, tenantId: TenantId): Promise<SessionView | null> {
+		const record = this.sessions.get(sessionId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `session(${sessionId})`)
+
+		const view = this.linkageView(tenantId)
+		return {
+			session: record.session,
+			children: orderChildren(getChildren(view, sessionId)),
+			ancestry: getAncestry(view, sessionId),
+		}
+	}
+
+	// Summary (§4.7 / §8.1) ---------------------------------------------------
+
+	async recordSummary(
+		summary: SessionSummaryRef & { materializedBy: 'kernel' },
+		tenantId: TenantId,
+	): Promise<void> {
+		if (summary.tenantId !== tenantId) {
+			throw new TenantIsolationError({
+				requested: tenantId,
+				resource: `summary(${summary.id}) payload`,
+			})
+		}
+		const sessionRecord = this.sessions.get(summary.sessionRef)
+		if (!sessionRecord) {
+			throw new Error(`Session ${summary.sessionRef} not found`)
+		}
+		this.assertTenant(sessionRecord.tenantId, tenantId, `session(${summary.sessionRef})`)
+
+		// Atomic within the call: summary persist + session status flip commit
+		// together. An existing summary with the same id is the recovery path —
+		// idempotently replay the status flip without duplicating the record.
+		const existing = this.summaries.get(summary.sessionRef)
+		if (existing && existing.summary.id !== summary.id) {
+			throw new SessionAlreadySummarizedError({
+				sessionId: summary.sessionRef,
+				existingSummaryId: existing.summary.id,
+			})
+		}
+
+		if (!existing) {
+			this.summaries.set(summary.sessionRef, { tenantId, summary })
+		}
+
+		if (SUMMARY_TERMINAL_FLIP_STATUSES.has(sessionRecord.session.status)) {
+			this.sessions.set(summary.sessionRef, {
+				tenantId,
+				session: {
+					...sessionRecord.session,
+					status: 'idle',
+					updatedAt: new Date(),
+				},
+			})
+		}
+	}
+
+	async getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null> {
+		const record = this.summaries.get(sessionId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `summary(${record.summary.id})`)
+		return record.summary
+	}
+
+	// Helpers -----------------------------------------------------------------
+
+	private assertTenant(actual: TenantId, requested: TenantId, resource: string): void {
+		if (actual !== requested) {
+			throw new TenantIsolationError({ requested, resource })
+		}
+	}
+
+	private linkageView(tenantId: TenantId): LinkageView {
+		return {
+			findChildSubSessions: (parentSessionId) => {
+				const matches: SubSession[] = []
+				for (const record of this.subSessions.values()) {
+					if (record.tenantId !== tenantId) continue
+					if (record.subSession.parentSessionId === parentSessionId) {
+						matches.push(record.subSession)
+					}
+				}
+				return matches
+			},
+			findParentSubSession: (childSessionId) => {
+				for (const record of this.subSessions.values()) {
+					if (record.tenantId !== tenantId) continue
+					if (record.subSession.childSessionId === childSessionId) {
+						return record.subSession
+					}
+				}
+				return null
+			},
+		}
+	}
+}

package/src/store/session/messages.ts

@@ -0,0 +1,21 @@
+/**
+ * SessionMessage — the persistence record for a {@link Message} in the
+ * session hierarchy.
+ *
+ * Rename of the legacy `ConversationMessage` concept, scoped by
+ * {@link SessionId} and carrying {@link TenantId} for the Convention #17
+ * key tuple (session-hierarchy.md §12.1). The `message` field preserves the
+ * full Run-scoped `Message` payload verbatim; the wrapper only adds
+ * addressability + tenant isolation.
+ */
+
+import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+
+export interface SessionMessage {
+	readonly id: MessageId
+	readonly sessionId: SessionId
+	readonly tenantId: TenantId
+	readonly message: Message
+	readonly at: Date
+}

package/src/types/agent/base.ts

@@ -1,9 +1,10 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, ThreadId } from '../ids/index.js'
+import type { RunId, SessionId, TenantId, ThreadId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { StopReason } from '../run/stop-reason.js'
+import type { ProjectId } from '../session/ids.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -22,8 +23,37 @@ export interface BaseAgentConfig {
 	permissionMode?: PermissionMode
 	env?: Record<string, string>
 
+	/**
+	 * @deprecated Use `projectId`. Kept as a migration-window mirror; when both
+	 * are present `projectId` wins. See session-hierarchy.md §13.1.
+	 */
 	threadId?: ThreadId
 
+	/**
+	 * Long-lived goal scope for the run. Required at runtime in 0.2.0 per
+	 * session-hierarchy.md §12.1 — `{@link ReactiveAgent}`, `{@link
+	 * SupervisorAgent}`, etc. reject configs missing this (`'X requires
+	 * sessionId, projectId, and tenantId in config (§12.1)'`).
+	 *
+	 * Kept optional at the TYPE level during the 0.2.x migration window
+	 * because {@link AgentManager} stamps this field AFTER `configBuilder`
+	 * returns (manager/agent/lifecycle.ts:228–230). That stamping path is
+	 * how every `@namzu/agents` configBuilder currently gets its tenant /
+	 * session / project triple; flipping the type to required without first
+	 * updating every {@link AgentFactoryOptions} consumer (which does not
+	 * carry these fields) would be a gratuitous downstream break.
+	 *
+	 * Tightening to required is Phase 9 Known Delta #6. The type-level flip
+	 * lands in 0.3.0 alongside `AgentFactoryOptions` gaining the triple.
+	 */
+	projectId?: ProjectId
+
+	/** Session under which the run executes. See `projectId` for the tightening plan. */
+	sessionId?: SessionId
+
+	/** Isolation boundary (Convention #17). See `projectId` for the tightening plan. */
+	tenantId?: TenantId
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/agent/task.ts

@@ -1,7 +1,10 @@
+import type { ActorRef } from '../../session/hierarchy/actor.js'
+import type { WorkspaceBackendKind } from '../../session/workspace/ref.js'
 import type { TokenUsage } from '../common/index.js'
-import type { RunId, TaskId, ThreadId } from '../ids/index.js'
+import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { RunEventListener } from '../run/events.js'
+import type { ProjectId } from '../session/ids.js'
 import type { AgentInput, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { Agent } from './core.js'
 import type { AgentFactoryOptions } from './factory.js'
@@ -19,6 +22,17 @@ export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 	return state === 'completed' || state === 'failed' || state === 'canceled' || state === 'rejected'
 }
 
+/**
+ * Context carried into {@link AgentManager.sendMessage}. Phase 6 promotes
+ * `tenantId`, `sessionId`, `projectId`, and `parentActor` to required fields —
+ * the spawn path is the ingress point for the session hierarchy; callers must
+ * provide the full scoping set (session-hierarchy.md §12.1 required-callsite
+ * matrix).
+ *
+ * `threadId` was removed — `projectId` owns the root scope. The deprecated
+ * alias `type ThreadId = ProjectId` still compiles for consumers transitioning
+ * off the name, but the shape no longer exposes a separate slot.
+ */
 export interface AgentTaskContext {
 	parentRunId: RunId
 
@@ -32,7 +46,24 @@ export interface AgentTaskContext {
 
 	factoryOptions?: AgentFactoryOptions
 
-	threadId?: ThreadId
+	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
+	tenantId: TenantId
+
+	/**
+	 * Parent session under which any sub-agent spawn is recorded. Required
+	 * in 0.2.0; a spawn cannot be attributed without it.
+	 */
+	sessionId: SessionId
+
+	/** Long-lived goal scope (replaces `threadId`). Required. */
+	projectId: ProjectId
+
+	/**
+	 * The actor invoking this task. Children built off this context stamp
+	 * their own `parentActor: ActorRef` linking back via the actor chain
+	 * (session-hierarchy.md §4.3 / §10.4).
+	 */
+	parentActor: ActorRef
 }
 
 export interface AgentTaskBudget {
@@ -66,6 +97,12 @@ export interface AgentTaskProgress {
 	recentActivities: string[]
 }
 
+/**
+ * Options accepted by {@link AgentManager.sendMessage}. Phase 6 adds the
+ * required sub-session spawn scope (`parentSessionId`, `tenantId`, `projectId`,
+ * `parentActor`) so the manager can create a SubSession + child Session +
+ * WorkspaceRef triple atomically on every spawn.
+ */
 export interface SendMessageOptions {
 	agentId: string
 
@@ -77,6 +114,25 @@ export interface SendMessageOptions {
 		tokenBudget?: number
 		timeoutMs?: number
 	}
+
+	/**
+	 * Parent session under which the new sub-session is created. Capacity
+	 * validation (depth + width) is applied against this session.
+	 */
+	parentSessionId: SessionId
+
+	tenantId: TenantId
+
+	projectId: ProjectId
+
+	/** The actor requesting the spawn — seeds the child's `parentActor`. */
+	parentActor: ActorRef
+
+	/**
+	 * Workspace backend to provision for the child session. Defaults to
+	 * `git-worktree` — the MVP reference backend from Phase 3.
+	 */
+	workspaceBackend?: WorkspaceBackendKind
 }
 
 export interface AgentManagerConfig {

package/src/types/conversation/index.ts

@@ -1,6 +1,13 @@
 import type { RunId, ThreadId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 
+/**
+ * @deprecated Use `SessionStore` from `@namzu/sdk` (import via
+ * `types/session/store.ts` or the root barrel). `ConversationStore` is
+ * thread-scoped and does not carry the `tenantId` required by
+ * session-hierarchy.md §12.1. Scheduled for removal in 0.3.0; the one-
+ * version migration window follows session-hierarchy.md §13.1.
+ */
 export interface ConversationStore {
 	loadMessages(threadId: ThreadId): Message[]