@namzu/sdk 13.0.0 → 13.1.0

package/src/store/session/__tests__/a-workspace-can-be-configured.test.ts

@@ -0,0 +1,210 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { TenantIsolationError } from '../../../session/errors.js'
+import type { TenantId } from '../../../types/ids/index.js'
+import type { SessionStore } from '../../../types/session/store.js'
+import { DiskSessionStore } from '../disk.js'
+import { InMemorySessionStore } from '../memory.js'
+
+/**
+ * Every project in existence ran at depth 4 and width 8.
+ *
+ * The config was hardcoded identically in both stores, `CreateProjectParams`
+ * was `{tenantId, name}`, and there was no `updateProject`. So a tenant with
+ * several workspaces could not give them different limits — which is most of
+ * what having several workspaces is for.
+ *
+ * Only the two fields something READS are settable. `ProjectConfig` declares
+ * eight; five enforcement sites read two of them. Exposing the other six would
+ * make dead fields easier to set, and a host that configures a retention policy
+ * and gets no error believes retention is on. `maxInterventionDepth` looks like
+ * an exception and is not: its three apparent readers are all comments.
+ *
+ * Both stores are driven by the same cases, because a reference implementation
+ * that disagrees with the durable one is worse than having only one.
+ */
+
+const TENANT = 'tnt_cfg' as TenantId
+const OTHER = 'tnt_other' as TenantId
+
+const dirs: string[] = []
+afterEach(async () => {
+	await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+	dirs.length = 0
+})
+
+async function diskStore(): Promise<SessionStore> {
+	const rootDir = await mkdtemp(join(tmpdir(), 'namzu-cfg-'))
+	dirs.push(rootDir)
+	return new DiskSessionStore({ rootDir })
+}
+
+const IMPLEMENTATIONS: ReadonlyArray<readonly [string, () => Promise<SessionStore>]> = [
+	['in memory', async () => new InMemorySessionStore()],
+	['on disk', diskStore],
+]
+
+describe.each(IMPLEMENTATIONS)('a workspace carries its own limits (%s)', (_name, build) => {
+	it('takes the limits it was created with', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2, maxDelegationWidth: 3 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(3)
+	})
+
+	it('keeps the defaults for anything not given', async () => {
+		const store = await build()
+
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		expect(project.config.maxDelegationDepth).toBe(2)
+		expect(project.config.maxDelegationWidth).toBe(8)
+	})
+
+	it('lets two workspaces of one tenant differ, which is the point', async () => {
+		const store = await build()
+
+		const narrow = await store.createProject(
+			{ tenantId: TENANT, name: 'narrow', config: { maxDelegationWidth: 1 } },
+			TENANT,
+		)
+		const wide = await store.createProject(
+			{ tenantId: TENANT, name: 'wide', config: { maxDelegationWidth: 16 } },
+			TENANT,
+		)
+
+		expect(narrow.config.maxDelegationWidth).toBe(1)
+		expect(wide.config.maxDelegationWidth).toBe(16)
+	})
+
+	it('changes a limit after the fact, and the change is readable back', async () => {
+		const store = await build()
+		const project = await store.createProject({ tenantId: TENANT, name: 'w' }, TENANT)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		expect((await store.getProject(project.id, TENANT))?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('leaves a limit it was not asked to change', async () => {
+		// Per field, not whole-value: raising the width says nothing about the
+		// depth, and resetting it would be an answer to a question nobody asked.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 2 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(project.id, { maxDelegationWidth: 12 }, TENANT)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(2)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('treats an explicitly undefined limit as "leave it", not "clear it"', async () => {
+		// The case the per-field guard exists for, and the one a plain spread
+		// gets wrong: `{...config}` with an explicit `undefined` key writes the
+		// undefined through and erases a limit the caller never mentioned. A
+		// caller building an update object programmatically produces exactly
+		// this shape.
+		const store = await build()
+		const project = await store.createProject(
+			{ tenantId: TENANT, name: 'w', config: { maxDelegationDepth: 3 } },
+			TENANT,
+		)
+
+		await store.updateProject?.(
+			project.id,
+			{ maxDelegationDepth: undefined, maxDelegationWidth: 12 },
+			TENANT,
+		)
+
+		const reloaded = await store.getProject(project.id, TENANT)
+		expect(reloaded?.config.maxDelegationDepth).toBe(3)
+		expect(reloaded?.config.maxDelegationWidth).toBe(12)
+	})
+
+	it('lists what this tenant owns, oldest first', async () => {
+		// Eight, spaced past the millisecond `createdAt` is measured in, so this
+		// is an assertion about age rather than about the tie-break below. With
+		// the sort dropped the disk store returns them in directory order, which
+		// is id-ascending — it matches creation order once in 8!.
+		const store = await build()
+		const created = []
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			created.push(await store.createProject({ tenantId: TENANT, name }, TENANT))
+			await new Promise((resolve) => setTimeout(resolve, 2))
+		}
+
+		const listed = await store.listProjects?.(TENANT)
+
+		expect(listed?.map((p) => p.id)).toEqual(created.map((p) => p.id))
+	})
+
+	it('stays a total order when several are created in the same millisecond', async () => {
+		// CI found this and a slower machine could not: on a fast filesystem
+		// projects routinely share a `createdAt`, and "oldest first" alone left
+		// the rest to `readdir`. A caller paginating a listing that reorders
+		// under it sees the same project twice and never sees another.
+		const store = await build()
+		for (const name of ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']) {
+			await store.createProject({ tenantId: TENANT, name }, TENANT)
+		}
+
+		const listed = (await store.listProjects?.(TENANT)) ?? []
+
+		expect(listed).toHaveLength(8)
+		for (let i = 1; i < listed.length; i++) {
+			const before = listed[i - 1]
+			const after = listed[i]
+			if (before === undefined || after === undefined) throw new Error('short listing')
+			const olderFirst = before.createdAt.getTime() < after.createdAt.getTime()
+			const tieByName =
+				before.createdAt.getTime() === after.createdAt.getTime() && before.id < after.id
+			expect({ pair: [before.name, after.name], ordered: olderFirst || tieByName }).toEqual({
+				pair: [before.name, after.name],
+				ordered: true,
+			})
+		}
+	})
+
+	it('omits another tenant from the listing rather than refusing', async () => {
+		// A listing is a question about what you own. Refusing would confirm
+		// that somebody else's project is there, which is the leak the tenant
+		// boundary exists to prevent.
+		const store = await build()
+		await store.createProject({ tenantId: TENANT, name: 'mine' }, TENANT)
+		await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		expect((await store.listProjects?.(TENANT))?.map((p) => p.name)).toEqual(['mine'])
+	})
+
+	it('refuses to reconfigure another tenant project', async () => {
+		// Reading a listing is a question; writing to somebody else's workspace
+		// is not, so this one throws.
+		const store = await build()
+		const theirs = await store.createProject({ tenantId: OTHER, name: 'theirs' }, OTHER)
+
+		await expect(
+			store.updateProject?.(theirs.id, { maxDelegationWidth: 99 }, TENANT),
+		).rejects.toBeInstanceOf(TenantIsolationError)
+	})
+
+	it('returns null for a project that does not exist', async () => {
+		const store = await build()
+
+		expect(await store.updateProject?.('prj_missing' as never, {}, TENANT)).toBeNull()
+	})
+})

package/src/store/session/disk.ts

@@ -35,6 +35,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -193,8 +194,8 @@ 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,
 			},
 			createdAt: now,
@@ -215,6 +216,66 @@ 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 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> {

package/src/store/session/memory.ts

@@ -20,6 +20,7 @@ import type {
 	CreateProjectParams,
 	CreateSessionParams,
 	CreateSubSessionParams,
+	ProjectConfigInput,
 	SessionStore,
 	SessionView,
 } from '../../types/session/store.js'
@@ -88,8 +89,8 @@ 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,
 			},
 			createdAt: now,
@@ -106,6 +107,49 @@ 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 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> {

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/session/store.ts

@@ -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,33 @@ 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[]>
+
 	// Session CRUD ------------------------------------------------------------
 
 	createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>