@namzu/sdk 0.1.8 → 0.2.0

package/src/types/ids/index.ts

@@ -1,7 +1,6 @@
-export type ThreadId = `thd_${string}`
 export type RunId = `run_${string}`
 export type MessageId = `msg_${string}`
-export type SessionId = `sess_${string}`
+export type SessionId = `ses_${string}`
 export type ToolCallId = `call_${string}`
 export type ActivityId = `act_${string}`
 export type TaskId = `task_${string}`
@@ -11,7 +10,7 @@ export type DocumentId = `doc_${string}`
 export type ChunkId = `chk_${string}`
 export type ConnectorId = `conn_${string}`
 export type ConnectorInstanceId = `ci_${string}`
-export type TenantId = `ten_${string}`
+export type TenantId = `tnt_${string}`
 export type CredentialId = `cred_${string}`
 export type ExecutionContextId = `ectx_${string}`
 export type MCPServerId = `mcp_${string}`
@@ -26,3 +25,42 @@ export type EmergencySaveId = `esave_${string}`
 export type MemoryId = `mem_${string}`
 export type PluginId = `plg_${string}`
 export type SandboxId = `sbx_${string}`
+
+// Actor identifiers (Session Hierarchy §4.3). Branded so actor refs cannot be
+// constructed from bare strings.
+export type UserId = `usr_${string}`
+export type AgentId = `agt_${string}`
+
+// Shared-store placeholder refs (Session Hierarchy §4.2 / §3.2). Full shapes
+// land in later phases; kept here as opaque branded IDs so ProjectConfig can
+// reference them today.
+export type MemoryStoreRef = `mms_${string}`
+export type VaultRef = `vlt_${string}`
+export type KnowledgeBaseRef = `kbs_${string}`
+
+// Session hierarchy IDs — live canonically here (Phase 9 Known Delta #4
+// collapse: previously split across `types/ids/` and `types/session/ids.ts`
+// with a circular re-export). Convention #2 branded IDs; prefixes mandated
+// by session-hierarchy.md §4. The `types/session/ids.ts` barrel re-exports
+// these for co-location ergonomics.
+export type ProjectId = `prj_${string}`
+export type SubSessionId = `sub_${string}`
+export type HandoffId = `hof_${string}`
+export type WorkspaceId = `wsp_${string}`
+export type SummaryId = `sum_${string}`
+export type DeliverableId = `del_${string}`
+
+/**
+ * @deprecated Use {@link ProjectId}. Alias retained for the 0.2.x migration
+ * window; will be removed in 0.3.0. See session-hierarchy.md §13.3.1.
+ */
+export type ThreadId = ProjectId
+
+/**
+ * Sentinel {@link TenantId} for legacy pre-0.2.0 runs rehomed by the
+ * boot-time filesystem migration (session-hierarchy.md §13.4.1). Consumers
+ * with strict tenant enforcement should either tag these records on first
+ * access or reject them until a real tenant is assigned — the kernel
+ * surfaces the sentinel but does not prescribe policy (Convention #17).
+ */
+export const UNKNOWN_TENANT_ID = 'tnt_unknown_legacy' as TenantId

package/src/types/invocation/__tests__/state.test.ts

@@ -3,20 +3,22 @@ import type { TenantId } from '../../ids/index.js'
 import { deriveChildState } from '../index.js'
 import type { InvocationState } from '../index.js'
 
+const ROOT_TENANT = 'tnt_root' as TenantId
+
 describe('InvocationState', () => {
 	describe('deriveChildState', () => {
-		it('should create child state with single agent in parentChain when parent is undefined', () => {
-			const childState = deriveChildState(undefined, 'agent-123')
+		it('seeds parentChain from a root seed when no parent state exists', () => {
+			const childState = deriveChildState({ tenantId: ROOT_TENANT }, 'agent-123')
 
 			expect(childState.parentChain).toEqual(['agent-123'])
-			expect(childState.tenantId).toBeUndefined()
+			expect(childState.tenantId).toBe(ROOT_TENANT)
 			expect(childState.metadata).toBeUndefined()
 			expect(childState.services).toBeUndefined()
 		})
 
-		it('should create child state with single agent in parentChain when parent has no parentChain', () => {
+		it('seeds parentChain when parent has no parentChain', () => {
 			const parent: InvocationState = {
-				tenantId: 'ten_abc' as TenantId,
+				tenantId: 'tnt_abc' as TenantId,
 				metadata: { userId: 'user-123' },
 			}
 
@@ -27,10 +29,10 @@ describe('InvocationState', () => {
 			expect(childState.metadata).toBe(parent.metadata)
 		})
 
-		it('should extend parentChain with current agent', () => {
+		it('extends parentChain with current agent', () => {
 			const parent: InvocationState = {
 				parentChain: ['supervisor', 'router'],
-				tenantId: 'ten_xyz' as TenantId,
+				tenantId: 'tnt_xyz' as TenantId,
 			}
 
 			const childState = deriveChildState(parent, 'worker-agent')
@@ -38,8 +40,8 @@ describe('InvocationState', () => {
 			expect(childState.parentChain).toEqual(['supervisor', 'router', 'worker-agent'])
 		})
 
-		it('should preserve tenantId through derivation', () => {
-			const tenantId = 'ten_tenant123' as TenantId
+		it('preserves tenantId through derivation', () => {
+			const tenantId = 'tnt_tenant123' as TenantId
 			const parent: InvocationState = {
 				tenantId,
 				parentChain: ['agent-1'],
@@ -50,13 +52,14 @@ describe('InvocationState', () => {
 			expect(childState.tenantId).toBe(tenantId)
 		})
 
-		it('should preserve metadata through derivation', () => {
+		it('preserves metadata through derivation', () => {
 			const metadata = {
 				userId: 'user-456',
-				sessionId: 'sess_789',
+				sessionId: 'ses_789',
 				correlationId: 'corr_abc',
 			}
 			const parent: InvocationState = {
+				tenantId: ROOT_TENANT,
 				metadata,
 				parentChain: ['agent-1'],
 			}
@@ -67,12 +70,13 @@ describe('InvocationState', () => {
 			expect(childState.metadata?.userId).toBe('user-456')
 		})
 
-		it('should preserve services through derivation', () => {
+		it('preserves services through derivation', () => {
 			const services = {
 				db: { pool: 'mock-pool' },
 				cache: { client: 'mock-redis' },
 			}
 			const parent: InvocationState = {
+				tenantId: ROOT_TENANT,
 				services,
 				parentChain: ['agent-1'],
 			}
@@ -82,12 +86,12 @@ describe('InvocationState', () => {
 			expect(childState.services).toBe(services)
 		})
 
-		it('should preserve all fields through multi-level derivation', () => {
-			const tenantId = 'ten_multi' as TenantId
+		it('preserves all fields through multi-level derivation', () => {
+			const tenantId = 'tnt_multi' as TenantId
 			const metadata = { userId: 'user-multi' }
 			const services = { db: 'postgres' }
 
-			const level1 = deriveChildState(undefined, 'supervisor')
+			const level1 = deriveChildState({ tenantId }, 'supervisor')
 			expect(level1.parentChain).toEqual(['supervisor'])
 
 			const parent: InvocationState = {
@@ -110,8 +114,9 @@ describe('InvocationState', () => {
 			expect(level3.services).toBe(services)
 		})
 
-		it('should create immutable parentChain', () => {
+		it('creates immutable parentChain', () => {
 			const parent: InvocationState = {
+				tenantId: ROOT_TENANT,
 				parentChain: ['agent-1'],
 			}
 
@@ -122,8 +127,9 @@ describe('InvocationState', () => {
 			expect(childState.parentChain).toEqual(['agent-1', 'agent-2'])
 		})
 
-		it('should handle empty parentChain in parent', () => {
+		it('handles empty parentChain in parent', () => {
 			const parent: InvocationState = {
+				tenantId: ROOT_TENANT,
 				parentChain: [],
 			}
 
@@ -132,25 +138,25 @@ describe('InvocationState', () => {
 			expect(childState.parentChain).toEqual(['agent-first'])
 		})
 
-		it('should allow complex agent IDs in parentChain', () => {
+		it('allows complex agent IDs in parentChain', () => {
 			const agentIds = ['supervisor-agent-123', 'router-multi-path', 'worker-task-handler']
 
-			let state: InvocationState | undefined
+			let state: InvocationState = { tenantId: ROOT_TENANT }
 			for (const agentId of agentIds) {
 				state = deriveChildState(state, agentId)
 			}
 
-			expect(state?.parentChain).toEqual(agentIds)
+			expect(state.parentChain).toEqual(agentIds)
 		})
 
-		it('should not mutate parent state', () => {
+		it('does not mutate parent state', () => {
 			const parent: InvocationState = {
 				parentChain: ['original'],
-				tenantId: 'ten_orig' as TenantId,
+				tenantId: 'tnt_orig' as TenantId,
 				metadata: { key: 'value' },
 			}
 
-			const originalParentChain = [...parent.parentChain!]
+			const originalParentChain = [...(parent.parentChain ?? [])]
 
 			deriveChildState(parent, 'child')
 
@@ -161,33 +167,34 @@ describe('InvocationState', () => {
 	})
 
 	describe('InvocationState immutability', () => {
-		it('should have readonly fields', () => {
+		it('has readonly fields', () => {
 			const state: InvocationState = {
-				tenantId: 'ten_test' as TenantId,
+				tenantId: 'tnt_test' as TenantId,
 				metadata: { key: 'value' },
 				services: { db: 'postgres' },
 				parentChain: ['agent-1'],
 			}
 
 			// Type system enforces immutability, so these assertions verify the type definitions
-			expect(state.tenantId).toBe('ten_test')
+			expect(state.tenantId).toBe('tnt_test')
 			expect(state.metadata).toBeDefined()
 			expect(state.services).toBeDefined()
 			expect(state.parentChain).toBeDefined()
 		})
 
-		it('should support undefined optional fields', () => {
+		it('supports undefined optional fields (tenantId still required)', () => {
 			const minimalState: InvocationState = {
+				tenantId: ROOT_TENANT,
 				parentChain: ['agent-1'],
 			}
 
-			expect(minimalState.tenantId).toBeUndefined()
+			expect(minimalState.tenantId).toBe(ROOT_TENANT)
 			expect(minimalState.metadata).toBeUndefined()
 			expect(minimalState.services).toBeUndefined()
 			expect(minimalState.parentChain).toEqual(['agent-1'])
 		})
 
-		it('should handle metadata with various types', () => {
+		it('handles metadata with various types', () => {
 			const metadata = {
 				userId: 'user-123',
 				count: 42,
@@ -197,6 +204,7 @@ describe('InvocationState', () => {
 			}
 
 			const state: InvocationState = {
+				tenantId: ROOT_TENANT,
 				metadata,
 			}
 

package/src/types/invocation/index.ts

@@ -14,8 +14,12 @@ import type { TenantId } from '../ids/index.js'
  * - Tools can access state via ToolContext.invocationState
  */
 export interface InvocationState {
-	/** Tenant context for multi-tenant isolation (if applicable) */
-	readonly tenantId?: TenantId
+	/**
+	 * Isolation boundary — required in 0.2.0 per session-hierarchy.md §12.1.
+	 * Every store accessor downstream branches on this id; omission is a
+	 * compile-time error.
+	 */
+	readonly tenantId: TenantId
 
 	/** Request-scoped metadata (user info, session, correlation IDs, etc.) */
 	readonly metadata?: Readonly<Record<string, unknown>>
@@ -27,6 +31,15 @@ export interface InvocationState {
 	readonly parentChain?: readonly string[]
 }
 
+/**
+ * Params for {@link deriveChildState} when the parent is absent. `tenantId`
+ * is required even at the top level — the kernel refuses to guess tenant
+ * identity (session-hierarchy.md §12.1).
+ */
+export interface DeriveChildStateRoot {
+	readonly tenantId: TenantId
+}
+
 /**
  * Create a child invocation state with the current agent appended to parentChain.
  *
@@ -34,22 +47,25 @@ export interface InvocationState {
  * to sub-agents. It ensures the full agent hierarchy is tracked for debugging,
  * logging, and tenant isolation validation.
  *
- * @param parent The parent invocation state (may be undefined for top-level agents)
+ * When `parent` is undefined (top-level agent), a minimal root context is
+ * required so `tenantId` can be seeded — see {@link DeriveChildStateRoot}.
+ * `InvocationState.tenantId` is required in 0.2.0 (§12.1).
+ *
+ * @param parent The parent invocation state, or a root seed carrying `tenantId`.
  * @param currentAgentId The ID of the agent making the delegation
  * @returns A new InvocationState with currentAgentId appended to parentChain
  */
 export function deriveChildState(
-	parent: InvocationState | undefined,
+	parent: InvocationState | DeriveChildStateRoot,
 	currentAgentId: string,
 ): InvocationState {
-	const parentChain = parent?.parentChain
-		? [...parent.parentChain, currentAgentId]
-		: [currentAgentId]
+	const existingChain = 'parentChain' in parent ? parent.parentChain : undefined
+	const parentChain = existingChain ? [...existingChain, currentAgentId] : [currentAgentId]
 
 	return {
-		tenantId: parent?.tenantId,
-		metadata: parent?.metadata,
-		services: parent?.services,
+		tenantId: parent.tenantId,
+		metadata: 'metadata' in parent ? parent.metadata : undefined,
+		services: 'services' in parent ? parent.services : undefined,
 		parentChain,
 	}
 }

package/src/types/run/config.ts

@@ -1,7 +1,8 @@
 import type { ModelPricing } from '../../utils/cost.js'
 import type { Logger } from '../../utils/logger.js'
-import type { RunId } from '../ids/index.js'
+import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { PermissionMode } from '../permission/index.js'
+import type { ProjectId } from '../session/ids.js'
 
 export interface AgentRunConfig {
 	model: string
@@ -20,6 +21,12 @@ export interface AgentRunConfig {
 	}
 }
 
+/**
+ * Config for {@link RunPersistence}. Phase 6 promotes `sessionId`, `tenantId`,
+ * and `projectId` to required — every Run must be attributed to a Session
+ * under a Project within a Tenant (session-hierarchy.md §12.1). The legacy
+ * `threadId`-only shape is gone.
+ */
 export interface RunPersistenceConfig {
 	runId: RunId
 	agentId: string
@@ -30,6 +37,10 @@ export interface RunPersistenceConfig {
 	pricing?: ModelPricing
 	log: Logger
 
+	sessionId: SessionId
+	tenantId: TenantId
+	projectId: ProjectId
+
 	parentRunId?: RunId
 
 	depth?: number

package/src/types/run/events.ts

@@ -1,3 +1,9 @@
+import type {
+	SubsessionIdledEvent,
+	SubsessionMessagedEvent,
+	SubsessionSpawnedEvent,
+} from '../../session/events/index.js'
+import type { Lineage } from '../../session/hierarchy/lineage.js'
 import type { ActivityStatus, ActivityType } from '../activity/index.js'
 import type { BaseAgentResult } from '../agent/base.js'
 import type { CostInfo, TokenUsage } from '../common/index.js'
@@ -9,7 +15,21 @@ import type { TaskStatus } from '../task/index.js'
 
 export type { StopReason } from './stop-reason.js'
 
-export type RunEvent =
+/**
+ * Additive envelope fields present on every {@link RunEvent} variant.
+ *
+ * Per session-hierarchy.md §10.1 evolution is additive and consumers filter
+ * by the `type` discriminator, never by field shape. 0.2.0+ emitters stamp
+ * `schemaVersion: 2`; older untagged events are treated as virtually v1 by
+ * readers. `lineage` is populated on sub-session emissions (§10.4) and left
+ * absent on root-session events.
+ */
+interface RunEventEnvelope {
+	schemaVersion?: 2
+	lineage?: Lineage
+}
+
+type CoreRunEvent =
 	| { type: 'run_started'; runId: RunId; systemPrompt?: string }
 	| { type: 'iteration_started'; runId: RunId; iteration: number }
 	| {
@@ -174,4 +194,19 @@ export type RunEvent =
 	  }
 	| { type: 'sandbox_destroyed'; runId: RunId; sandboxId: SandboxId }
 
+/**
+ * Discriminated union of all run-scoped events emitted by the kernel.
+ *
+ * Convention #16: `type` is the sole discriminator for exhaustive switches;
+ * envelope fields (`schemaVersion`, `lineage`) are additive and never
+ * participate in discrimination. Sub-session lifecycle variants
+ * (`subsession_spawned`, `subsession_messaged`, `subsession_idled`) carry a
+ * required `lineage` — see session-hierarchy.md §10.4.
+ */
+export type RunEvent =
+	| (CoreRunEvent & RunEventEnvelope)
+	| SubsessionSpawnedEvent
+	| SubsessionMessagedEvent
+	| SubsessionIdledEvent
+
 export type RunEventListener = (event: RunEvent) => void | Promise<void>

package/src/types/run/index.ts

@@ -1,6 +1,14 @@
 export * from './stop-reason.js'
 export * from './config.js'
 export * from './state.js'
+// Note: `./status.js` is intentionally NOT re-exported via `export *` from
+// this barrel — the domain `RunStatus` type (session-hierarchy.md §4.6)
+// shares its name with the deprecated wire alias `RunStatus` in
+// `contracts/api.ts` (the canonical wire name is now `WireRunStatus`, see
+// Task 10 Phase 9). The root barrel re-exports the domain `RunStatus`
+// explicitly via `export type { RunStatus } from './types/run/status.js'`
+// so external consumers of `@namzu/sdk` land on the domain enum while
+// `@namzu/contracts` continues to own the wire shape.
 export * from './events.js'
 export * from './metadata.js'
 export * from './emergency.js'

package/src/types/run/metadata.ts

@@ -1,9 +1,32 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
-import type { RunId, TaskId, ThreadId } from '../ids/index.js'
+import type { RunId, TaskId, TenantId, ThreadId } from '../ids/index.js'
+import type { ProjectId } from '../session/ids.js'
 import type { StopReason } from './stop-reason.js'
 
+/**
+ * Denormalized metadata for a run.
+ *
+ * See session-hierarchy.md §4.6, §10.1, and §12.1.
+ *
+ * 0.2.0 promotes `projectId` and `tenantId` to required fields. `threadId`
+ * remains as a deprecated mirror of `projectId` for the 0.2.x migration
+ * window — consumers should prefer `projectId` and fall back to `threadId`
+ * only for legacy records. 0.3.x removes `threadId` entirely (§13.1).
+ */
 export interface RunMetadata {
 	id: RunId
+	/**
+	 * Long-lived goal scope. Required in 0.2.0. Replaces the root-scope role
+	 * `threadId` played in 0.1.x.
+	 */
+	projectId: ProjectId
+	/** Isolation boundary (Convention #17). Required in 0.2.0. */
+	tenantId: TenantId
+	/**
+	 * @deprecated Use {@link RunMetadata.projectId}. Mirror retained for the
+	 * 0.2.x migration window; scheduled for removal in 0.3.0 per
+	 * session-hierarchy.md §13.1.
+	 */
 	threadId: ThreadId
 	agentId: string
 	agentName: string

package/src/types/run/status.ts

@@ -0,0 +1,33 @@
+/**
+ * Domain Run status enum. See session-hierarchy.md §4.6 + §5.2 state machine.
+ *
+ * Distinct from the wire-side {@link WireRunStatus} in `contracts/api.ts`,
+ * which maps these states onto HTTP payload shapes (`completed` /
+ * `cancelling` / `expired`). Keep this enum purely the domain surface; any
+ * consumer that needs the HTTP representation should translate at the bridge
+ * boundary.
+ *
+ * Variants:
+ *  - `queued` — run created, not yet started.
+ *  - `running` — iteration loop in flight.
+ *  - `awaiting_hitl` — synchronous-wait on a HITL gate (user present).
+ *  - `awaiting_hitl_resolution` — persisted-wait after a HITL timeout under
+ *    `HITLConfig.onTimeout = 'pause_run_until_resolved'`. User absent; Run
+ *    persists until resolved or cancelled (permission-policies.md §13.3).
+ *  - `awaiting_subsession` — parent Run has delegated to a child SubSession
+ *    and is suspended until the Materializer seals the child's summary.
+ *    Session-level fan-in treats this as `active` (delegation in flight
+ *    means the parent IS active). See session-hierarchy.md §5.1.
+ *  - `succeeded` — terminal, run completed without error.
+ *  - `failed` — terminal, run errored out.
+ *  - `cancelled` — terminal, explicitly cancelled.
+ */
+export type RunStatus =
+	| 'queued'
+	| 'running'
+	| 'awaiting_hitl'
+	| 'awaiting_hitl_resolution'
+	| 'awaiting_subsession'
+	| 'succeeded'
+	| 'failed'
+	| 'cancelled'

package/src/types/session/ids.ts

@@ -0,0 +1,34 @@
+/**
+ * Session hierarchy branded ID re-export barrel.
+ *
+ * Canonical definitions live in `../ids/index.ts` (Phase 9 Known Delta #4
+ * collapse: previously this file declared ProjectId/SubSessionId/etc. and
+ * `types/ids/` re-exported them — a circular re-export that TypeScript
+ * resolved cleanly but smelled). All session IDs now live in one place;
+ * this barrel exists solely for ergonomic co-location with session-scoped
+ * callers (they already import from `types/session/`).
+ */
+
+export type {
+	ProjectId,
+	SubSessionId,
+	HandoffId,
+	WorkspaceId,
+	SummaryId,
+	DeliverableId,
+	SessionId,
+	TenantId,
+	RunId,
+	AgentId,
+	UserId,
+	TaskId,
+	ThreadId,
+} from '../ids/index.js'
+
+import type { ProjectId } from '../ids/index.js'
+
+/**
+ * @deprecated Use {@link ProjectId}. Alias kept for one version migration
+ * window; scheduled for removal in 0.3.0 per session-hierarchy.md §13.3.1.
+ */
+export type ThreadIdDeprecated = ProjectId

package/src/types/session/index.ts

@@ -0,0 +1,28 @@
+// Sub-barrel for session-hierarchy type surface.
+// Concrete definitions live in sibling files; re-export them here so other
+// modules import via `../types/session/index.js`.
+
+export type {
+	ProjectId,
+	SubSessionId,
+	HandoffId,
+	WorkspaceId,
+	SummaryId,
+	DeliverableId,
+	SessionId,
+	TenantId,
+	RunId,
+	AgentId,
+	UserId,
+	TaskId,
+	ThreadId,
+	ThreadIdDeprecated,
+} from './ids.js'
+
+export type {
+	SessionStore,
+	SessionView,
+	CreateProjectParams,
+	CreateSessionParams,
+	CreateSubSessionParams,
+} from './store.js'