@namzu/sdk 0.1.8 → 0.3.0

package/src/agents/RouterAgent.ts

@@ -84,6 +84,11 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 			targetRoute = fallback
 		}
 
+		if (!config.invocationState) {
+			throw new Error(
+				'RouterAgent requires invocationState with tenantId in config (session-hierarchy.md §12.1).',
+			)
+		}
 		const childInvocationState = deriveChildState(config.invocationState, this.metadata.id)
 		const delegateResult = await targetRoute.agent.run(
 			input,

package/src/agents/SupervisorAgent.ts

@@ -3,6 +3,7 @@ import { LocalTaskGateway } from '../gateway/local.js'
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import type { LaunchedTaskMeta } from '../runtime/query/iteration/phases/context.js'
+import type { ActorRef } from '../session/hierarchy/actor.js'
 import { buildCoordinatorTools } from '../tools/coordinator/index.js'
 import type { TaskGateway } from '../types/agent/gateway.js'
 import type {
@@ -12,7 +13,7 @@ import type {
 	SupervisorAgentResult,
 } from '../types/agent/index.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
-import type { TaskId, ThreadId } from '../types/ids/index.js'
+import type { AgentId, TaskId } from '../types/ids/index.js'
 import { deriveChildState } from '../types/invocation/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
@@ -42,8 +43,20 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 		const startTime = Date.now()
 		const runId = this.createRunId()
 
-		if (!config.threadId) {
-			throw new Error('SupervisorAgent requires threadId in config')
+		if (!config.sessionId || !config.threadId || !config.projectId || !config.tenantId) {
+			throw new Error(
+				'SupervisorAgent requires sessionId, threadId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
+			)
+		}
+		const sessionId = config.sessionId
+		const threadId = config.threadId
+		const projectId = config.projectId
+		const tenantId = config.tenantId
+
+		const parentActor: ActorRef = {
+			kind: 'agent',
+			agentId: this.metadata.id as AgentId,
+			tenantId,
 		}
 
 		let gateway: TaskGateway
@@ -71,7 +84,11 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					remaining: config.tokenBudget,
 				},
 				factoryOptions: mergedFactoryOptions,
-				threadId: config.threadId as ThreadId,
+				tenantId,
+				threadId,
+				sessionId,
+				projectId,
+				parentActor,
 			}
 			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input)
 		} else {
@@ -99,7 +116,10 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 			tools.register(tool)
 		}
 
-		const childInvocationState = deriveChildState(config.invocationState, this.metadata.id)
+		const childInvocationState = deriveChildState(
+			config.invocationState ?? { tenantId },
+			this.metadata.id,
+		)
 
 		const run = await drainQuery(
 			{
@@ -119,7 +139,10 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				workingDirectory: input.workingDirectory,
 				messages: input.messages,
 				signal: input.signal,
-				threadId: config.threadId as ThreadId,
+				sessionId,
+				threadId,
+				projectId,
+				tenantId,
 				runId,
 				parentRunId: config.parentRunId,
 				depth: config.depth,

package/src/bridge/a2a/index.ts

@@ -10,7 +10,6 @@ export {
 
 export {
 	messageToA2A,
-	threadMessageToA2A,
 	extractTextFromA2AMessage,
 	a2aMessageToInput,
 } from './message.js'

package/src/bridge/a2a/mapper.ts

@@ -157,6 +157,13 @@ const MAPPING: {
 	sandbox_created: null,
 	sandbox_exec: null,
 	sandbox_destroyed: null,
+
+	// Sub-session lifecycle events (session-hierarchy.md §10.4). These are
+	// in-flight visibility signals for the kernel bus; the A2A bridge does not
+	// surface them today.
+	subsession_spawned: null,
+	subsession_messaged: null,
+	subsession_idled: null,
 }
 
 export function mapRunToA2AEvent(event: RunEvent, contextId?: string): A2AStreamEvent | null {

package/src/bridge/a2a/message.ts

@@ -1,4 +1,3 @@
-import type { ThreadMessage } from '../../contracts/index.js'
 import type { A2AMessage, A2AMessageRole, A2APart, TextPart } from '../../types/a2a/index.js'
 import type { Message, MessageRole } from '../../types/message/index.js'
 
@@ -48,37 +47,6 @@ export function messageToA2A(msg: Message): A2AMessage {
 	}
 }
 
-export function threadMessageToA2A(msg: ThreadMessage): A2AMessage {
-	const parts: A2APart[] = []
-
-	if (msg.content) {
-		parts.push({ kind: 'text', text: msg.content })
-	}
-
-	if (msg.tool_calls) {
-		for (const tc of msg.tool_calls) {
-			parts.push({
-				kind: 'data',
-				data: {
-					toolCallId: tc.id,
-					name: tc.function.name,
-					arguments: tc.function.arguments,
-				},
-				mimeType: 'application/x-namzu-tool-call',
-			})
-		}
-	}
-
-	if (parts.length === 0) {
-		parts.push({ kind: 'text', text: '' })
-	}
-
-	return {
-		role: toA2ARole(msg.role),
-		parts,
-	}
-}
-
 export function extractTextFromA2AMessage(msg: A2AMessage): string {
 	return msg.parts
 		.filter((p): p is TextPart => p.kind === 'text')

package/src/bridge/a2a/task.ts

@@ -1,5 +1,5 @@
 import { RUN_STATUS_TO_A2A, TERMINAL_STATES } from '../../constants/a2a/index.js'
-import type { Run, RunConfig, RunStatus, ThreadMessage } from '../../contracts/index.js'
+import type { Run, RunConfig, WireRunStatus } from '../../contracts/index.js'
 import type {
 	A2AArtifact,
 	A2AMessage,
@@ -8,13 +8,14 @@ import type {
 	A2ATaskState,
 	A2ATaskStatus,
 } from '../../types/a2a/index.js'
-import { extractTextFromA2AMessage, threadMessageToA2A } from './message.js'
+import type { Message } from '../../types/message/index.js'
+import { extractTextFromA2AMessage, messageToA2A } from './message.js'
 
 export function isTerminalState(state: A2ATaskState): boolean {
 	return TERMINAL_STATES.has(state)
 }
 
-export function runStatusToA2AState(status: RunStatus): A2ATaskState {
+export function runStatusToA2AState(status: WireRunStatus): A2ATaskState {
 	return RUN_STATUS_TO_A2A[status]
 }
 
@@ -53,12 +54,12 @@ function buildArtifacts(run: Run): A2AArtifact[] | undefined {
 	]
 }
 
-export function runToA2ATask(run: Run, messages?: readonly ThreadMessage[]): A2ATask {
+export function runToA2ATask(run: Run, messages?: readonly Message[]): A2ATask {
 	return {
 		id: run.id,
-		contextId: run.thread_id ?? undefined,
+		contextId: run.project_id ?? undefined,
 		status: buildTaskStatus(run),
-		history: messages?.map(threadMessageToA2A),
+		history: messages?.map(messageToA2A),
 		artifacts: buildArtifacts(run),
 		metadata: {
 			agent_id: run.agent_id,
@@ -71,7 +72,7 @@ export function runToA2ATask(run: Run, messages?: readonly ThreadMessage[]): A2A
 export interface CreateRunFromA2A {
 	readonly agentId: string
 	readonly input: string
-	readonly threadId?: string
+	readonly projectId?: string
 	readonly config: RunConfig
 }
 
@@ -99,7 +100,7 @@ export function a2aMessageToCreateRun(
 	return {
 		agentId,
 		input,
-		threadId: params.contextId,
+		projectId: params.contextId,
 		config,
 	}
 }

package/src/bridge/sse/mapper.ts

@@ -272,6 +272,13 @@ const MAPPING: {
 		wire: 'sandbox.destroyed',
 		transform: (e, runId) => ({ run_id: runId, sandbox_id: e.sandboxId }),
 	},
+
+	// Sub-session lifecycle events (session-hierarchy.md §10.4). These are
+	// in-flight signals carried on the kernel bus; the SSE wire surface does
+	// not emit them today.
+	subsession_spawned: null,
+	subsession_messaged: null,
+	subsession_idled: null,
 }
 
 export function mapRunToStreamEvent(event: RunEvent, runId: RunId): MappedStreamEvent | null {
@@ -283,7 +290,7 @@ export function mapRunToStreamEvent(event: RunEvent, runId: RunId): MappedStream
 		runId,
 	)
 
-	const annotated = event as Record<string, unknown>
+	const annotated = event as unknown as Record<string, unknown>
 	if ('sourceAgentId' in annotated && annotated.sourceAgentId) {
 		data.source_agent_id = annotated.sourceAgentId
 	}

package/src/constants/a2a/index.ts

@@ -1,9 +1,9 @@
-import type { RunStatus } from '../../contracts/index.js'
+import type { WireRunStatus } from '../../contracts/index.js'
 import type { A2ATaskState } from '../../types/a2a/index.js'
 
 export const A2A_PROTOCOL_VERSION = '0.3.0'
 
-export const RUN_STATUS_TO_A2A: Record<RunStatus, A2ATaskState> = {
+export const RUN_STATUS_TO_A2A: Record<WireRunStatus, A2ATaskState> = {
 	queued: 'pending',
 	running: 'running',
 	completed: 'completed',

package/src/contracts/api.ts

@@ -1,7 +1,7 @@
 import type { AgentCapabilities, AgentType } from '../types/agent/base.js'
 import type { MessageRole } from '../types/message/index.js'
 import type { StopReason } from '../types/run/events.js'
-import type { MessageId, RunId, SessionId, ThreadId } from './ids.js'
+import type { ProjectId, RunId, SessionId } from './ids.js'
 
 export type { MessageRole, StopReason, AgentType, AgentCapabilities }
 
@@ -27,14 +27,6 @@ export interface AgentInfo {
 	capabilities?: AgentCapabilities
 }
 
-export interface Thread {
-	id: ThreadId
-	created_at: ISOTimestamp
-	updated_at: ISOTimestamp
-	metadata: Record<string, string>
-	message_count: number
-}
-
 export interface ToolCallInfo {
 	id: string
 	type: 'function'
@@ -44,30 +36,22 @@ export interface ToolCallInfo {
 	}
 }
 
-export interface ThreadMessage {
-	id: MessageId
-	thread_id: ThreadId
-	role: MessageRole
-	content: string | null
-	created_at: ISOTimestamp
-	run_id?: RunId
-	tool_call_id?: string
-	tool_calls?: ToolCallInfo[]
-	metadata?: Record<string, unknown>
-}
-
-export interface CreateThreadRequest {
-	metadata?: Record<string, string>
-	messages?: CreateMessageRequest[]
-}
-
 export interface CreateMessageRequest {
 	role: 'user'
 	content: string
 	metadata?: Record<string, unknown>
 }
 
-export type RunStatus =
+/**
+ * Wire-side run status for HTTP / A2A / SSE payloads.
+ *
+ * Distinct from the domain {@link import('../types/run/status.js').RunStatus}
+ * which models the kernel state machine. The wire enum collapses domain
+ * variants onto the HTTP-facing shape (e.g. domain `succeeded` → wire
+ * `completed`; domain `awaiting_hitl*` → wire `running`; domain
+ * `awaiting_subsession` → wire `running`).
+ */
+export type WireRunStatus =
 	| 'queued'
 	| 'running'
 	| 'completed'
@@ -83,11 +67,11 @@ export type RunStopReason = StopReason
 
 export interface Run {
 	id: RunId
-	thread_id: ThreadId | null
+	project_id: ProjectId | null
 	session_id?: SessionId
 	agent_id: string
 	agent_name?: string
-	status: RunStatus
+	status: WireRunStatus
 	stop_reason?: RunStopReason
 	created_at: ISOTimestamp
 	started_at?: ISOTimestamp
@@ -111,7 +95,7 @@ export interface RunHierarchyNode {
 	run_id: RunId
 	agent_id: string
 	depth: number
-	status: RunStatus
+	status: WireRunStatus
 	children: RunHierarchyNode[]
 }
 

package/src/contracts/ids.ts

@@ -1 +1 @@
-export type { ThreadId, RunId, MessageId, SessionId } from '../types/ids/index.js'
+export type { ProjectId, RunId, MessageId, SessionId } from '../types/ids/index.js'

package/src/contracts/index.ts

@@ -10,12 +10,9 @@ export type {
 	ISOTimestamp,
 	AgentDefaults,
 	AgentInfo,
-	Thread,
 	ToolCallInfo,
-	ThreadMessage,
-	CreateThreadRequest,
 	CreateMessageRequest,
-	RunStatus,
+	WireRunStatus,
 	RunStopReason,
 	Run,
 	RunHierarchyNode,
@@ -32,15 +29,14 @@ export type {
 	ApiError,
 } from './api.js'
 
-export type { ThreadId, RunId, MessageId, SessionId } from './ids.js'
+export type { ProjectId, RunId, MessageId, SessionId } from './ids.js'
 
 export {
-	ThreadIdSchema,
+	ProjectIdSchema,
 	RunIdSchema,
 	MessageIdSchema,
 	RunConfigSchema,
 	CreateMessageSchema,
-	CreateThreadSchema,
 	CreateRunSchema,
 	CreateStatelessRunSchema,
 	PaginationSchema,

package/src/contracts/schemas.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 
-export const ThreadIdSchema = z.string().regex(/^thd_[a-z0-9]+$/, 'Invalid thread ID format')
+export const ProjectIdSchema = z.string().regex(/^prj_[a-z0-9]+$/, 'Invalid project ID format')
 export const RunIdSchema = z.string().regex(/^run_[a-z0-9]+$/, 'Invalid run ID format')
 export const MessageIdSchema = z.string().regex(/^msg_[a-z0-9]+$/, 'Invalid message ID format')
 
@@ -24,13 +24,6 @@ export const CreateMessageSchema = z
 	})
 	.strict()
 
-export const CreateThreadSchema = z
-	.object({
-		metadata: z.record(z.string()).optional(),
-		messages: z.array(CreateMessageSchema).optional(),
-	})
-	.strict()
-
 export const CreateRunSchema = z
 	.object({
 		agent_id: z.string().min(1, 'agent_id is required'),

package/src/gateway/local.ts

@@ -40,6 +40,12 @@ export class LocalTaskGateway implements TaskGateway {
 					taskStore: this.parentInput?.taskStore,
 					runtimeToolOverrides: this.parentInput?.runtimeToolOverrides,
 				},
+				// Phase 6: spawn scope propagates from the gateway's task context.
+				// The caller built it at SupervisorAgent boundary (§12.1).
+				parentSessionId: this.taskContext.sessionId,
+				tenantId: this.taskContext.tenantId,
+				projectId: this.taskContext.projectId,
+				parentActor: this.taskContext.parentActor,
 			},
 			{ ...this.taskContext, budgetTracker: { ...this.taskContext.budgetTracker } },
 			this.listener,

package/src/index.ts

@@ -23,6 +23,11 @@ export * from './types/common/index.js'
 export * from './types/tool/index.js'
 export * from './types/permission/index.js'
 export * from './types/run/index.js'
+// Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Re-exported
+// explicitly because `types/run/index.js` intentionally skips `status.js` to
+// avoid colliding with the deprecated wire alias in `contracts/api.ts`
+// (renamed to `WireRunStatus` in 0.2.0 — Phase 9 Known Delta #2).
+export type { RunStatus } from './types/run/status.js'
 export * from './types/provider/index.js'
 export * from './types/agent/index.js'
 export * from './types/decision/index.js'
@@ -37,7 +42,6 @@ export * from './types/execution/index.js'
 export * from './types/connector/index.js'
 export * from './types/skills/index.js'
 export * from './types/a2a/index.js'
-export * from './types/conversation/index.js'
 export * from './types/router/index.js'
 export * from './types/advisory/index.js'
 export * from './types/memory/index.js'
@@ -46,6 +50,10 @@ export * from './types/sandbox/index.js'
 export * from './types/structured-output/index.js'
 export * from './types/invocation/index.js'
 export * from './types/computer-use/index.js'
+// Session hierarchy types (Phase 9 — public API freeze for 0.2.0).
+// Types-only re-export; runtime primitives come via `./session/index.js`
+// and `./store/session/index.js` below.
+export type * from './types/session/index.js'
 
 export {
 	AdvisorRegistry,
@@ -131,8 +139,6 @@ export {
 	InMemoryTaskStore,
 	DiskTaskStore,
 	type DiskTaskStoreConfig,
-	InMemoryConversationStore,
-	type InMemoryConversationStoreConfig,
 	InMemoryMemoryIndex,
 	InMemoryMemoryStore,
 	DiskMemoryStore,
@@ -291,7 +297,6 @@ export {
 	runStatusToA2AState,
 	a2aMessageToCreateRun,
 	messageToA2A,
-	threadMessageToA2A,
 	extractTextFromA2AMessage,
 	a2aMessageToInput,
 	mapRunToA2AEvent,
@@ -332,6 +337,11 @@ export {
 export type { PlatformMetrics } from './telemetry/index.js'
 export * from './telemetry/attributes.js'
 
+// Session hierarchy runtime primitives (Phase 9 — public API freeze for 0.2.0).
+// Convention #4: root barrel imports sub-barrels only, never concrete files.
+export * from './session/index.js'
+export * from './store/session/index.js'
+
 export {
 	WorkingStateManager,
 	serializeState,