@namzu/sdk 0.1.7 → 0.2.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,19 @@ 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.projectId || !config.tenantId) {
+			throw new Error(
+				'SupervisorAgent requires sessionId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
+			)
+		}
+		const sessionId = config.sessionId
+		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 +83,10 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					remaining: config.tokenBudget,
 				},
 				factoryOptions: mergedFactoryOptions,
-				threadId: config.threadId as ThreadId,
+				tenantId,
+				sessionId,
+				projectId,
+				parentActor,
 			}
 			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input)
 		} else {
@@ -99,7 +114,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 +137,9 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				workingDirectory: input.workingDirectory,
 				messages: input.messages,
 				signal: input.signal,
-				threadId: config.threadId as ThreadId,
+				sessionId,
+				projectId,
+				tenantId,
 				runId,
 				parentRunId: config.parentRunId,
 				depth: config.depth,

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/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, ThreadMessage, WireRunStatus } from '../../contracts/index.js'
 import type {
 	A2AArtifact,
 	A2AMessage,
@@ -14,7 +14,7 @@ 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]
 }
 

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

@@ -67,7 +67,20 @@ export interface CreateMessageRequest {
 	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 (session-hierarchy.md §4.6 + §5.2).
+ * 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`).
+ *
+ * Renamed from `RunStatus` to `WireRunStatus` in 0.2.0 to disambiguate from
+ * the domain enum; a deprecated alias `RunStatus = WireRunStatus` is retained
+ * at the bottom of this module for one migration window.
+ */
+export type WireRunStatus =
 	| 'queued'
 	| 'running'
 	| 'completed'
@@ -87,7 +100,7 @@ export interface Run {
 	session_id?: SessionId
 	agent_id: string
 	agent_name?: string
-	status: RunStatus
+	status: WireRunStatus
 	stop_reason?: RunStopReason
 	created_at: ISOTimestamp
 	started_at?: ISOTimestamp
@@ -111,7 +124,7 @@ export interface RunHierarchyNode {
 	run_id: RunId
 	agent_id: string
 	depth: number
-	status: RunStatus
+	status: WireRunStatus
 	children: RunHierarchyNode[]
 }
 
@@ -221,3 +234,10 @@ export interface ApiError {
 		param?: string
 	}
 }
+
+/**
+ * @deprecated Use {@link WireRunStatus}. Alias retained for one migration
+ * window (0.2.x); scheduled for removal in 0.3.0. Renamed to disambiguate
+ * from the domain `RunStatus` in `../types/run/status.js`.
+ */
+export type RunStatus = WireRunStatus

package/src/contracts/index.ts

@@ -15,6 +15,8 @@ export type {
 	ThreadMessage,
 	CreateThreadRequest,
 	CreateMessageRequest,
+	WireRunStatus,
+	/** @deprecated Use {@link WireRunStatus}. */
 	RunStatus,
 	RunStopReason,
 	Run,

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'
@@ -46,6 +51,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,
@@ -332,6 +341,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,