@namzu/sdk 13.0.0 → 14.0.0

package/src/store/session/disk.ts

@@ -23,11 +23,11 @@
 
 import { appendFile, mkdir, readFile, readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
-import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
+import { StaleProjectError, StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, SummaryId, ThreadId } from '../../types/session/ids.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -35,6 +35,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -79,6 +80,10 @@ interface PersistedProject {
 	tenantId: TenantId
 	name: string
 	config: Project['config']
+	/** Absent in files written before the workspace gained a status. */
+	status?: ProjectStatus
+	/** Absent in files written before the workspace gained a CAS counter. */
+	ownerVersion?: number
 	createdAt: string
 	updatedAt: string
 }
@@ -193,10 +198,12 @@ export class DiskSessionStore implements SessionStore {
 			tenantId,
 			name: params.name,
 			config: {
-				maxDelegationDepth: 4,
-				maxDelegationWidth: 8,
+				maxDelegationDepth: params.config?.maxDelegationDepth ?? 4,
+				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
+			status: 'open',
+			ownerVersion: 0,
 			createdAt: now,
 			updatedAt: now,
 		}
@@ -215,6 +222,95 @@ export class DiskSessionStore implements SessionStore {
 		return deserializeProject(raw)
 	}
 
+	async updateProject(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null> {
+		const existing = await this.getProject(projectId, tenantId)
+		if (!existing) return null
+		// Per field, like the in-memory store: an omitted limit is left alone
+		// rather than reset.
+		const project: Project = {
+			...existing,
+			config: {
+				...existing.config,
+				...(config.maxDelegationDepth !== undefined
+					? { maxDelegationDepth: config.maxDelegationDepth }
+					: {}),
+				...(config.maxDelegationWidth !== undefined
+					? { maxDelegationWidth: config.maxDelegationWidth }
+					: {}),
+			},
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(
+			join(this.projectDir(projectId), 'project.json'),
+			serializeProject(project),
+		)
+		return project
+	}
+
+	async setProjectStatus(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null> {
+		const existing = await this.getProject(projectId, tenantId)
+		if (!existing) return null
+		// Against the version on disk, not the caller's copy of it.
+		if (existing.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleProjectError({
+				projectId,
+				expectedOwnerVersion,
+				actualOwnerVersion: existing.ownerVersion,
+			})
+		}
+		const project: Project = {
+			...existing,
+			status,
+			ownerVersion: existing.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		await atomicWriteJson(
+			join(this.projectDir(projectId), 'project.json'),
+			serializeProject(project),
+		)
+		return project
+	}
+
+	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
+		// Read from the directory rather than the lazily-built index: the index
+		// only knows about projects this instance has already touched, so a
+		// listing built from it would omit everything written by a previous
+		// process — which for a store whose whole point is durability is the
+		// wrong answer.
+		const projectsRoot = join(this.rootDir, 'projects')
+		let entries: string[]
+		try {
+			entries = await readdir(projectsRoot)
+		} catch {
+			return []
+		}
+
+		const found: Project[] = []
+		for (const entry of entries) {
+			const raw = await readJson<PersistedProject>(join(projectsRoot, entry, 'project.json'))
+			if (!raw) continue
+			// Another tenant's project is absent, not an error — a listing is a
+			// question about what you own, and refusing would leak that
+			// somebody else's project is there.
+			if (raw.tenantId !== tenantId) continue
+			found.push(deserializeProject(raw))
+		}
+		// Tie-broken by id — see the in-memory store. On a fast filesystem two
+		// projects share a millisecond routinely, and without this the order
+		// came from readdir.
+		found.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id))
+		return found
+	}
+
 	// Session CRUD ------------------------------------------------------------
 
 	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
@@ -308,6 +404,40 @@ export class DiskSessionStore implements SessionStore {
 		return results
 	}
 
+	async listSessionsByProject(
+		projectId: ProjectId,
+		tenantId: TenantId,
+	): Promise<readonly Session[]> {
+		// One directory, not the whole root: sessions live under their project,
+		// so this is the cheap direction. `listSessions` has to scan every
+		// project precisely because `threadId` is denormalised onto the record
+		// rather than expressed in the layout.
+		const sessionsRoot = join(this.projectDir(projectId), 'sessions')
+		let sessionDirs: string[]
+		try {
+			sessionDirs = await readdir(sessionsRoot)
+		} catch (err) {
+			const code = (err as NodeJS.ErrnoException).code
+			if (code === 'ENOENT') return []
+			throw err
+		}
+
+		const results: Session[] = []
+		for (const rawSessionId of sessionDirs) {
+			if (!rawSessionId.startsWith('ses_')) continue
+			const path = join(sessionsRoot, rawSessionId)
+			const raw = await readJson<PersistedSession>(join(path, 'session.json'))
+			if (!raw) continue
+			if (raw.tenantId !== tenantId) continue
+			results.push(deserializeSession(raw))
+			this.sessionIndex.set(raw.id, { sessionId: raw.id, projectId, path })
+		}
+		results.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return results
+	}
+
 	async updateSession(
 		session: Session,
 		tenantId: TenantId,
@@ -849,6 +979,8 @@ function serializeProject(p: Project): PersistedProject {
 		tenantId: p.tenantId,
 		name: p.name,
 		config: p.config,
+		status: p.status,
+		ownerVersion: p.ownerVersion,
 		createdAt: p.createdAt.toISOString(),
 		updatedAt: p.updatedAt.toISOString(),
 	}
@@ -860,6 +992,12 @@ function deserializeProject(p: PersistedProject): Project {
 		tenantId: p.tenantId,
 		name: p.name,
 		config: p.config,
+		// A project.json written before these fields existed reads as an open
+		// workspace at version 0, which is what it was. Leaving `ownerVersion`
+		// undefined would be worse than a wrong default: every compare-and-set
+		// against it would fail, so an existing store could never be closed.
+		status: p.status ?? 'open',
+		ownerVersion: p.ownerVersion ?? 0,
 		createdAt: new Date(p.createdAt),
 		updatedAt: new Date(p.updatedAt),
 	}

package/src/store/session/memory.ts

@@ -8,11 +8,11 @@
  * (Convention #5 deny-by-default, session-hierarchy.md §12.2).
  */
 
-import { StaleSessionError, TenantIsolationError } from '../../session/errors.js'
+import { StaleProjectError, StaleSessionError, TenantIsolationError } from '../../session/errors.js'
 import { SessionAlreadySummarizedError } from '../../session/summary/errors.js'
 import type { MessageId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { Session } from '../../types/session/entity.js'
 import type { ProjectId, SubSessionId, ThreadId } from '../../types/session/ids.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -20,6 +20,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -88,10 +89,12 @@ export class InMemorySessionStore implements SessionStore {
 			tenantId,
 			name: params.name,
 			config: {
-				maxDelegationDepth: 4,
-				maxDelegationWidth: 8,
+				maxDelegationDepth: params.config?.maxDelegationDepth ?? 4,
+				maxDelegationWidth: params.config?.maxDelegationWidth ?? 8,
 				maxInterventionDepth: 10,
 			},
+			status: 'open',
+			ownerVersion: 0,
 			createdAt: now,
 			updatedAt: now,
 		}
@@ -106,6 +109,78 @@ export class InMemorySessionStore implements SessionStore {
 		return record.project
 	}
 
+	async updateProject(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null> {
+		const record = this.projects.get(projectId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `project(${projectId})`)
+		// Per field: an omitted limit is left alone rather than reset, because a
+		// caller raising the width is saying nothing about the depth.
+		const project: Project = {
+			...record.project,
+			config: {
+				...record.project.config,
+				...(config.maxDelegationDepth !== undefined
+					? { maxDelegationDepth: config.maxDelegationDepth }
+					: {}),
+				...(config.maxDelegationWidth !== undefined
+					? { maxDelegationWidth: config.maxDelegationWidth }
+					: {}),
+			},
+			updatedAt: new Date(),
+		}
+		this.projects.set(projectId, { tenantId, project })
+		return project
+	}
+
+	async setProjectStatus(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null> {
+		const record = this.projects.get(projectId)
+		if (!record) return null
+		this.assertTenant(record.tenantId, tenantId, `project(${projectId})`)
+		// Against the STORED version, not the caller's copy of it — comparing a
+		// value against itself is the shape the session CAS was written wrong in
+		// the first time.
+		if (record.project.ownerVersion !== expectedOwnerVersion) {
+			throw new StaleProjectError({
+				projectId,
+				expectedOwnerVersion,
+				actualOwnerVersion: record.project.ownerVersion,
+			})
+		}
+		const project: Project = {
+			...record.project,
+			status,
+			ownerVersion: record.project.ownerVersion + 1,
+			updatedAt: new Date(),
+		}
+		this.projects.set(projectId, { tenantId, project })
+		return project
+	}
+
+	async listProjects(tenantId: TenantId): Promise<readonly Project[]> {
+		const matches: Project[] = []
+		for (const record of this.projects.values()) {
+			if (record.tenantId !== tenantId) continue
+			matches.push(record.project)
+		}
+		// Tie-broken by id, because two projects created in the same
+		// millisecond otherwise fall back to insertion or directory order and
+		// "oldest first" stops being a total order. A caller paginating a
+		// listing that reorders under it sees items move between pages.
+		matches.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return matches
+	}
+
 	// Session CRUD ------------------------------------------------------------
 
 	async createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session> {
@@ -151,6 +226,22 @@ export class InMemorySessionStore implements SessionStore {
 		return matches
 	}
 
+	async listSessionsByProject(
+		projectId: ProjectId,
+		tenantId: TenantId,
+	): Promise<readonly Session[]> {
+		const matches: Session[] = []
+		for (const record of this.sessions.values()) {
+			if (record.tenantId !== tenantId) continue
+			if (record.session.projectId !== projectId) continue
+			matches.push(record.session)
+		}
+		matches.sort(
+			(a, b) => a.createdAt.getTime() - b.createdAt.getTime() || a.id.localeCompare(b.id),
+		)
+		return matches
+	}
+
 	async updateSession(
 		session: Session,
 		tenantId: TenantId,

package/src/tools/coordinator/agent.ts

@@ -146,6 +146,13 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 				// surface, and the one it exports as the canonical shape —
 				// did not.
 				...(context.parentSpan ? { parentSpan: context.parentSpan } : {}),
+				// The parent's environment, which is the whole point of setting
+				// one: a delegate that cannot see it runs against different
+				// services than the run that launched it, silently.
+				// `ToolContext.env` is the parent's own resolved map, per run.
+				...(Object.keys(context.env ?? {}).length > 0
+					? { configOverrides: { env: context.env } }
+					: {}),
 			})
 
 			onTaskLaunched?.(handle.taskId, {

package/src/tools/coordinator/index.ts

@@ -484,6 +484,12 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				// Hang the child run off THIS tool's span, so the delegation
 				// shows up inside the turn that asked for it.
 				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
+				// Same as the `Agent` tool: a delegate inherits the environment
+				// its parent was given, or it runs against different services
+				// than the run that asked for the work.
+				...(Object.keys(_context.env ?? {}).length > 0
+					? { configOverrides: { env: _context.env } }
+					: {}),
 			})
 
 			// Whose task this is. The inbox ignores completions for anything it

package/src/types/agent/base.ts

@@ -22,6 +22,29 @@ export interface BaseAgentConfig {
 	maxResponseTokens?: number
 	costLimitUsd?: number
 	permissionMode?: PermissionMode
+
+	/**
+	 * Extra environment variables for this agent's tools and sandboxed
+	 * commands, merged over whatever ambient environment the execution path
+	 * supplies. Inherited by every delegated descendant.
+	 *
+	 * **Configuration, not credentials** — and that is a property of the
+	 * CHANNEL rather than a judgement about any particular value. This map is
+	 * copied into every child, is readable by any tool that can run a command,
+	 * and enters a model's context and the run transcript the moment something
+	 * echoes it. Nothing here is scoped, redacted, or revocable.
+	 *
+	 * A value that authenticates to a host belongs on the brokered credential
+	 * path instead, where the process holds a placeholder and the real value is
+	 * attached per-host on egress — so it is never in the environment, never in
+	 * a transcript, and never inherited by a child that had no business with it.
+	 *
+	 * Inheritance was broken until it was not: a child built through a
+	 * `configBuilder` never received this at all, because the builder is
+	 * written by whoever registered the agent and cannot forward a field it was
+	 * never told about. It is stamped after the builder returns now, for the
+	 * same reason `parentSpan` and `resumeHandler` are.
+	 */
 	env?: Record<string, string>
 
 	/**

package/src/types/project/entity.ts

@@ -27,15 +27,33 @@ export interface ProjectConfig {
 	retentionPolicy?: RetentionPolicy
 }
 
+/**
+ * Whether the workspace accepts new work.
+ *
+ * Owner-managed, like the status it replaces: a project does not derive
+ * `archived` from having no live sessions, because "empty right now" and
+ * "closed" are different facts and only one of them is a decision.
+ */
+export type ProjectStatus = 'open' | 'archived'
+
 /**
  * Long-lived goal scope that owns shared memory, vaults, knowledge bases,
  * and deliverables across sessions. See session-hierarchy.md §4.2.
+ *
+ * `status` is the gate the ingress paths read: an archived project accepts no
+ * new session and no handoff. It lives here rather than on Thread because the
+ * project is the thing a tenant actually closes — a workspace with its own
+ * limits, its own environment, and its own memory — and closing it has to mean
+ * something to the code, not only to a listing.
  */
 export interface Project {
 	id: ProjectId
 	tenantId: TenantId
 	name: string
 	config: ProjectConfig
+	status: ProjectStatus
+	/** CAS counter for status transitions. Mirrors `Session.ownerVersion`. */
+	ownerVersion: number
 	createdAt: Date
 	updatedAt: Date
 }

package/src/types/session/store.ts

@@ -6,7 +6,7 @@
  * API — extensions land alongside their consumers.
  */
 
-import type { Project } from '../../types/project/entity.js'
+import type { Project, ProjectStatus } from '../../types/project/entity.js'
 import type { ActorRef } from '../../types/session/actor.js'
 import type { Session } from '../../types/session/entity.js'
 import type { SessionMessage } from '../../types/session/messages.js'
@@ -65,9 +65,42 @@ export interface CreateSubSessionParams {
  * is out of scope for this phase (session-hierarchy.md §11 defers the project
  * store to a later phase).
  */
+/**
+ * The part of a Project's configuration a caller may actually set.
+ *
+ * **Exactly the fields something reads.** `ProjectConfig` declares eight; five
+ * enforcement sites read two of them, and the other six have zero readers in
+ * production — `maxInterventionDepth` included, whose three apparent hits are
+ * all comments claiming a wiring that does not exist. Exposing those here
+ * would make a dead field *easier to set*, which is worse than leaving it
+ * unreachable: a host would configure a retention policy, get no error, and
+ * believe retention was on.
+ *
+ * The rule is the repo's own: name the code that reads a declaration before
+ * shipping it. When a field gains a reader it gains a line here in the same
+ * change, and not before.
+ */
+export interface ProjectConfigInput {
+	/** Read by the spawn path and both handoff paths. Default 4. */
+	maxDelegationDepth?: number
+	/** Read by the spawn path and broadcast handoff. Default 8. */
+	maxDelegationWidth?: number
+}
+
 export interface CreateProjectParams {
 	tenantId: TenantId
 	name: string
+
+	/**
+	 * Per-workspace limits. Omitted fields keep the defaults.
+	 *
+	 * Until this existed every project in existence ran at depth 4 / width 8,
+	 * because the config was hardcoded identically in both stores and there was
+	 * no way to write one afterwards. A tenant with several workspaces could
+	 * not give them different limits, which is most of what having several
+	 * workspaces is for.
+	 */
+	config?: ProjectConfigInput
 }
 
 /**
@@ -99,6 +132,56 @@ export interface SessionStore {
 
 	getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>
 
+	/**
+	 * Change a Project's limits after it exists. OPTIONAL.
+	 *
+	 * Optional because widening a store interface is invisible to callers and
+	 * fatal to implementors: a host with its own `SessionStore` should not stop
+	 * compiling because the SDK grew a method. Callers check for it; the two
+	 * stores here implement it.
+	 *
+	 * Only the fields in {@link ProjectConfigInput} can move, and an omitted
+	 * field is left alone rather than reset — a caller raising the width is not
+	 * saying anything about the depth. Returns the updated Project, or `null`
+	 * if it does not exist.
+	 */
+	updateProject?(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null>
+
+	/**
+	 * Every Project this tenant owns, oldest first. OPTIONAL, same reasoning.
+	 *
+	 * The tenant is the isolation boundary, so this is scoped to it and to
+	 * nothing else — there is no level above Project to filter by.
+	 */
+	listProjects?(tenantId: TenantId): Promise<readonly Project[]>
+
+	/**
+	 * Open or close a workspace. OPTIONAL, same reasoning as the two above.
+	 *
+	 * Compare-and-set on {@link Project.ownerVersion}: pass the version you
+	 * read, and a concurrent writer makes this throw `StaleProjectError`
+	 * instead of silently winning. On success the stored version is bumped.
+	 *
+	 * Both directions, because a workspace is long-lived and closing one by
+	 * mistake should not be permanent — unlike the Thread status this replaces,
+	 * which only ever went one way. Returns `null` if the project does not
+	 * exist; writing to another tenant's project throws.
+	 *
+	 * This is the store-level write. The precondition that no live session is
+	 * attached belongs to {@link import('../../manager/project/lifecycle.js').ProjectManager},
+	 * because the store deliberately holds no view of what is running.
+	 */
+	setProjectStatus?(
+		projectId: ProjectId,
+		status: ProjectStatus,
+		tenantId: TenantId,
+		expectedOwnerVersion: number,
+	): Promise<Project | null>
+
 	// Session CRUD ------------------------------------------------------------
 
 	createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>
@@ -153,6 +236,17 @@ export interface SessionStore {
 	 */
 	listSessions(threadId: ThreadId, tenantId: TenantId): Promise<readonly Session[]>
 
+	/**
+	 * Every Session attached to a workspace, oldest first. OPTIONAL.
+	 *
+	 * The project-scoped sibling of {@link SessionStore.listSessions}, and the
+	 * one the archive precondition reads: closing a workspace has to know what
+	 * is still running in it, and "what is running in this thread" was never
+	 * the question — a project can hold sessions across many threads, and after
+	 * the Thread level is removed it is the only grouping left.
+	 */
+	listSessionsByProject?(projectId: ProjectId, tenantId: TenantId): Promise<readonly Session[]>
+
 	/**
 	 * Hard-delete a session. Idempotent — absent sessions succeed as a no-op.
 	 * Rejects with `TenantIsolationError` on cross-tenant access.