@namzu/sdk 42.0.2 → 44.0.0

package/src/agents/budget.ts

@@ -1,19 +1,77 @@
-import { TokenBudget } from '../run/token-budget.js'
-import { openTokenBudget } from '../store/run/token-budget-disk.js'
+import { resolveNamzuHome } from '../session/home.js'
+import { SessionPaths, ensureProject } from '../session/paths.js'
+import {
+	DiskSessionTokenBudgetStore,
+	InMemorySessionTokenBudgetStore,
+	SessionTokenBudget,
+	type SessionTokenBudgetStore,
+	openSessionTokenBudget,
+} from '../store/budget/index.js'
+import { InMemorySessionLog } from '../store/session-log/index.js'
 import type { AgentInput, BaseAgentConfig } from '../types/agent/base.js'
-import type { RunId } from '../types/ids/index.js'
+import type { SessionId, TurnId } from '../types/ids/index.js'
 
-/** Resolve one authority before a composite agent constructs its scheduler. */
+/** The turn a composite agent is about to run, which its ledger is keyed by. */
+export interface AgentTurn {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+}
+
+/**
+ * Held per in-memory session log, so every turn of one in-memory session
+ * finds its ledgers in the same place and nothing reaches the disk.
+ */
+const inMemoryLedgers = new WeakMap<InMemorySessionLog, InMemorySessionTokenBudgetStore>()
+
+/**
+ * Where a root turn's ledger lives when the agent was handed none:
+ *
+ * - beside an in-memory session log with no `paths`: in memory, held for
+ *   that log;
+ * - otherwise on disk, at `<session-id>/budgets/<turn-id>.json` in the
+ *   project the config's `paths` (or the working directory under
+ *   `NAMZU_HOME`) names.
+ */
+async function ledgerStore(
+	input: AgentInput,
+	config: BaseAgentConfig,
+): Promise<SessionTokenBudgetStore> {
+	const log = config.sessionLog
+	if (log instanceof InMemorySessionLog && config.paths === undefined) {
+		let store = inMemoryLedgers.get(log)
+		if (!store) {
+			store = new InMemorySessionTokenBudgetStore()
+			inMemoryLedgers.set(log, store)
+		}
+		return store
+	}
+	if (config.paths) return new DiskSessionTokenBudgetStore({ paths: config.paths })
+	const home = resolveNamzuHome()
+	const project = await ensureProject({ home, cwd: input.workingDirectory })
+	return new DiskSessionTokenBudgetStore({
+		paths: new SessionPaths({ home, slug: project.slug }),
+	})
+}
+
+/**
+ * Resolve one authority before a composite agent constructs its scheduler.
+ *
+ * An inherited budget (a delegated child's reservation, or a host's) is bound
+ * to this turn with `bindTurn`, so its spend is attributed to the child
+ * session's turn while it stays keyed by the root turn that opened the
+ * ledger. A root turn opens a ledger of its own, keyed by
+ * `(sessionId, turnId)`: a new turn gets a new ledger and its own limit.
+ */
 export async function resolveAgentBudget(
 	input: AgentInput,
 	config: BaseAgentConfig,
-	runId: RunId,
-): Promise<TokenBudget> {
+	turn: AgentTurn,
+): Promise<SessionTokenBudget> {
 	if (!Number.isSafeInteger(config.tokenBudget) || config.tokenBudget < 0) {
 		throw new Error('Agent token budget must be a nonnegative safe integer')
 	}
 	if (config.budget) {
-		config.budget.bindRun(runId)
+		config.budget.bindTurn(turn.sessionId, turn.turnId)
 		if (
 			config.tokenBudget > 0 &&
 			(config.budget.limit === 0 || config.tokenBudget < config.budget.limit)
@@ -23,20 +81,19 @@ export async function resolveAgentBudget(
 		await config.budget.flush()
 		return config.budget
 	}
-	if (config.parentRunId) {
+	if (config.parentSessionId) {
 		throw new Error('A delegated agent requires its inherited token budget authority')
 	}
-	const { tenantId, projectId, sessionId } = config
+	const scope = { rootSessionId: turn.sessionId, rootTurnId: turn.turnId }
 	const budget =
-		tenantId && projectId && sessionId
-			? await openTokenBudget({
-					scope: { tenantId, projectId, sessionId, runId },
+		config.tenantId && config.projectId && config.sessionId
+			? await openSessionTokenBudget({
+					scope,
 					limit: config.tokenBudget,
-					pathBuilder: config.pathBuilder,
-					workingDirectory: input.workingDirectory,
+					store: await ledgerStore(input, config),
 				})
-			: TokenBudget.create(config.tokenBudget, runId)
-	budget.bindRun(runId)
+			: SessionTokenBudget.create(config.tokenBudget, scope)
+	budget.bindTurn(turn.sessionId, turn.turnId)
 	await budget.flush()
 	return budget
 }

package/src/agents/defineAgent.ts

@@ -8,7 +8,7 @@ import type {
 	BaseAgentConfig,
 	BaseAgentResult,
 } from '../types/agent/index.js'
-import type { RunEventListener } from '../types/run/index.js'
+import type { SessionEventListener } from '../types/session/events.js'
 
 export interface DefineAgentOptions<
 	TConfig extends BaseAgentConfig = BaseAgentConfig,
@@ -21,7 +21,7 @@ export interface DefineAgentOptions<
 	category: string
 	description: string
 	capabilities?: Partial<AgentCapabilities>
-	run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
+	run(input: AgentInput, config: TConfig, listener?: SessionEventListener): Promise<TResult>
 	cancel?(): Promise<void>
 }
 
@@ -45,7 +45,11 @@ export function defineAgent<
 		type: options.type,
 		metadata,
 
-		async run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult> {
+		async run(
+			input: AgentInput,
+			config: TConfig,
+			listener?: SessionEventListener,
+		): Promise<TResult> {
 			return options.run(input, config, listener)
 		},
 

package/src/agents/handle.ts

@@ -5,15 +5,15 @@ import type { TenantId, TopicId } from '../types/ids/index.js'
 import type { Message } from '../types/message/index.js'
 
 /**
- * The object a host holds between runs.
+ * The object a host holds between turns.
  *
  * There was none. A host could not ask whether the agent was running, and
  * had nowhere to put "when you next run, start with this" — so it either
- * held a steer until it observed a run starting, or carried the text itself
+ * held a steer until it observed a turn starting, or carried the text itself
  * and passed it manually on the next `run()` call.
  *
  * Two delivery targets, each with a stated lifetime, and no silent third
- * state. `steer` reaches the run that is happening; `queueForNextRun`
+ * state. `steer` reaches the turn that is happening; `queueForNextTurn`
  * reaches the one that has not started. `steer` on an idle handle THROWS
  * rather than accepting into a queue nothing will read — that refusal is
  * the design, because the alternative is a host believing it redirected an
@@ -21,14 +21,12 @@ import type { Message } from '../types/message/index.js'
  */
 
 /**
- * Whether a run is in flight, as this handle sees it.
+ * Whether a turn is in flight, as this handle sees it.
  *
- * NOT `AgentStatus` — that name is taken by a deprecated alias of
- * `RunExecutionStatus` whose own test records that it never typed an agent
- * and is being removed in the next major. Reusing it here would silently
- * change what a consumer's `AgentStatus` MEANS rather than failing their
- * build, which is the worse of the two outcomes and the one a deprecation
- * window exists to avoid.
+ * NOT `AgentStatus` — that name was a deprecated alias of the execution
+ * status which never typed an agent. Reusing it here would silently change
+ * what a consumer's `AgentStatus` MEANS rather than failing their build,
+ * which is the worse of the two outcomes.
  */
 export type AgentHandleStatus = 'idle' | 'running'
 
@@ -38,7 +36,7 @@ export class AgentNotRunningError extends NamzuError {
 		super({
 			code: 'invalid_config',
 			message:
-				'steer() needs a run in flight — this agent is idle. Use queueForNextRun() to leave a message for the next one.',
+				'steer() needs a turn in flight — this agent is idle. Use queueForNextTurn() to leave a message for the next one.',
 			details: {},
 			retryable: false,
 		})
@@ -49,15 +47,15 @@ export class AgentNotRunningError extends NamzuError {
 export interface AgentHandle {
 	readonly status: AgentHandleStatus
 	/**
-	 * Hand guidance to the run happening now.
+	 * Hand guidance to the turn happening now.
 	 *
 	 * Reaches the model at the next turn boundary whether or not a tool is
 	 * in flight — the channel rides a settled tool result when there is one,
 	 * and the loop delivers the remainder otherwise.
 	 */
 	steer(text: string): void
-	/** Leave a message for the run that has not started yet. */
-	queueForNextRun(message: Message): Promise<void>
+	/** Leave a message for the turn that has not started yet. */
+	queueForNextTurn(message: Message): Promise<void>
 }
 
 export interface AgentHandleOptions {
@@ -85,20 +83,20 @@ export function createAgentHandle(options: AgentHandleOptions): AgentHandle {
 		},
 
 		steer(text: string): void {
-			// Refused, not rerouted. Quietly forwarding to `queueForNextRun`
+			// Refused, not rerouted. Quietly forwarding to `queueForNextTurn`
 			// would be a host asking to redirect what is happening now and
-			// getting a message delivered minutes later to a different run —
+			// getting a message delivered minutes later to a different turn —
 			// which is worse than an error, because nothing says it happened.
 			if (!options.isRunning()) throw new AgentNotRunningError()
 			options.steering.steer(text)
 		},
 
-		async queueForNextRun(message: Message): Promise<void> {
+		async queueForNextTurn(message: Message): Promise<void> {
 			if (!options.topicStateStore) {
 				throw new NamzuError({
 					code: 'invalid_config',
 					message:
-						'queueForNextRun() needs a topic state store; this handle was built without one, so there is nowhere to leave the message.',
+						'queueForNextTurn() needs a topic state store; this handle was built without one, so there is nowhere to leave the message.',
 					details: { topicId: options.topicId },
 					retryable: false,
 				})
@@ -109,7 +107,7 @@ export function createAgentHandle(options: AgentHandleOptions): AgentHandle {
 }
 
 /**
- * Add a message to the topic's next-run queue, under compare-and-set.
+ * Add a message to the topic's next-turn queue, under compare-and-set.
  *
  * Read-modify-write against the record's revision, so two hosts queueing
  * for one conversation cannot silently drop each other's message — the

package/src/agents/lock.ts

@@ -12,14 +12,14 @@ export class ConcurrentInvocationError extends Error {
 
 	constructor(agentId: string) {
 		// Names the remedy, because the refusal alone sent readers looking for a
-		// concurrency bug in their own code. An agent instance holds per-run
-		// state — an abort controller and the run id — so two overlapping runs
+		// concurrency bug in their own code. An agent instance holds per-turn
+		// state — an abort controller and the turn id — so two overlapping turns
 		// on one shell would cancel each other; the answer is a second shell,
 		// not a second attempt. Delegated spawns get one automatically via
-		// `Agent.forRun`, so reaching this from a fan-out means the agent
+		// `Agent.forTurn`, so reaching this from a fan-out means the agent
 		// could not be rebuilt and wants `AgentDefinition.createAgent`.
 		super(
-			`Agent ${agentId} is already processing. Concurrent invocations of one instance are not allowed, because its abort controller and run id are instance state and two runs would cancel each other. Run a second instance instead — or, for a delegated spawn, give its AgentDefinition a \`createAgent\` factory so each child gets its own.`,
+			`Agent ${agentId} is already processing. Concurrent invocations of one instance are not allowed, because its abort controller and turn id are instance state and two turns would cancel each other. Run a second instance instead — or, for a delegated spawn, give its AgentDefinition a \`createAgent\` factory so each child gets its own.`,
 		)
 		this.name = 'ConcurrentInvocationError'
 		this.agentId = agentId

package/src/agents/runAgent.ts

@@ -1,12 +1,16 @@
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { type QueryParams, drainQuery } from '../runtime/query/index.js'
 import type { ProjectInstructionContext } from '../runtime/query/project-instructions.js'
+import { resolveNamzuHome } from '../session/home.js'
+import { SessionPaths, ensureProject } from '../session/paths.js'
+import { InMemorySessionLog } from '../store/session-log/index.js'
 import type { AuthorizationGateConfig } from '../types/authorization/index.js'
 import type { ProjectId, SessionId, TenantId, TopicId } from '../types/ids/index.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../types/provider/index.js'
-import type { Run, RunEventListener } from '../types/run/index.js'
 import type { SandboxProvider } from '../types/sandbox/index.js'
+import type { SessionEventListener } from '../types/session/events.js'
+import type { Turn } from '../types/session/turn.js'
 import type { Skill } from '../types/skills/index.js'
 import type { StructuredOutputConfig } from '../types/structured-output/index.js'
 import type { ToolRegistryContract } from '../types/tool/index.js'
@@ -18,7 +22,7 @@ import {
 } from '../utils/id.js'
 
 /**
- * The session a run belongs to.
+ * The session a turn belongs to.
  *
  * Every field is generated when absent, and the generated values come back on
  * the result so a second turn can be handed the same ones. That pairing is the
@@ -32,12 +36,20 @@ import {
  * refused at the first delegation with `Project <id> not found for tenant
  * <id> — spawn rejected`, which is the enforcement site behaving correctly:
  * delegation limits live on the project, and a missing project has no limits
- * to read. A run that has to delegate should be given the id returned by
+ * to read. A turn that has to delegate should be given the id returned by
  * `store.createProject()`.
  */
 export interface AgentIdentity {
 	sessionId?: SessionId
 	topicId?: TopicId
+	/**
+	 * Omitted: the project the working directory stands for, read from (or
+	 * minted once into) `~/.namzu/projects/<slug>/project.json` by
+	 * `ensureProject`, so every turn in one directory shares a Project. A
+	 * session held in memory with no `paths` gets a fresh id and writes
+	 * nothing. A host whose `paths` name a slug of its own passes the id. The
+	 * other three are minted per call when omitted.
+	 */
 	projectId?: ProjectId
 	tenantId?: TenantId
 }
@@ -71,7 +83,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	 *
 	 * The front door needs its own way to say this, because the registry it
 	 * was handed — usually the host's, assembled before this call — is not a
-	 * place a run can reach. Absent installs the shipped default
+	 * place a turn can reach. Absent installs the shipped default
 	 * ({@link DEFAULT_TOOL_RESULT_GUARDRAILS}: a connected server's result
 	 * that restates the request is refused). **An empty array is how a caller
 	 * turns that off**, and it is the reason this option is here at all: a
@@ -81,8 +93,8 @@ export interface RunAgentOptions extends AgentIdentity {
 	toolResultGuardrails?: readonly import('../types/guardrail/index.js').ToolResultGuardrailSpec[]
 	/** Execute sandbox-aware tools inside this provider's boundary. */
 	sandboxProvider?: SandboxProvider
-	/** What a supplied sandbox is rooted at and its per-run limits. */
-	sandbox?: import('../types/run/config.js').AgentRunConfig['sandbox']
+	/** What a supplied sandbox is rooted at and its per-turn limits. */
+	sandbox?: import('../types/session/config.js').TurnConfig['sandbox']
 	/** Sandbox teardown wait; defaults to 30 seconds and `0` is unbounded. */
 	sandboxTeardownTimeoutMs?: number
 
@@ -91,7 +103,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	 *
 	 * The kernel has taken these since it had a prompt builder; this door did
 	 * not forward them, so a caller who assembled skills — `@namzu/project`
-	 * reads a whole `skills/` directory — handed them over and got a run that
+	 * reads a whole `skills/` directory — handed them over and got a turn that
 	 * had never heard of them. Silent, because the `drainQuery` call below was
 	 * cast, and a cast seam reports nothing when a field goes missing.
 	 */
@@ -104,7 +116,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	 * library front door and the wrong one for a host that hands this an agent
 	 * directory it did not write. The kernel builds a `AuthorizationGate` from
 	 * this and consults it on every call; without it there is nothing to
-	 * consult, so a front-door run is strictly less mediated than a kernel one.
+	 * consult, so a front-door turn is strictly less mediated than a kernel one.
 	 */
 	/**
 	 * @deprecated Renamed to `authorizationGate`. Removed in the next major.
@@ -117,10 +129,14 @@ export interface RunAgentOptions extends AgentIdentity {
 	/** Defaults to the current working directory. */
 	workingDirectory?: string
 
-	/** Host-owned state layout, independent of the tool working directory. */
-	pathBuilder?: QueryParams['pathBuilder']
-	/** Optional evidence store; omitted uses the resolved disk layout. */
-	runStore?: QueryParams['runStore']
+	/** Host-owned state layout (`NAMZU_HOME` and the project slug), independent of the tool working directory. */
+	paths?: QueryParams['paths']
+	/**
+	 * The session log this turn appends to; omitted uses the log in the
+	 * resolved layout. An `InMemorySessionLog` keeps the whole session in
+	 * memory.
+	 */
+	sessionLog?: QueryParams['sessionLog']
 	/** Optional checkpoint store; omitted uses the resolved disk layout. */
 	checkpointStore?: QueryParams['checkpointStore']
 
@@ -128,7 +144,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	maxIterations?: number
 	/** Default 200,000 cumulative tokens; 0 is unlimited and still metered. */
 	tokenBudget?: number
-	/** Default five minutes; 0 disables the run deadline. */
+	/** Default five minutes; 0 disables the turn deadline. */
 	timeoutMs?: number
 	/** Maximum provider-stream silence; defaults to five minutes. `0` disables. */
 	streamIdleTimeoutMs?: number
@@ -147,7 +163,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	 * structured output throughout and this function never forwarded the
 	 * config, so the single most convenient way into the kernel was the one way
 	 * that could not produce a typed answer. Present, the validated value comes
-	 * back on {@link RunAgentResult.structuredOutput} and on `run`.
+	 * back on {@link RunAgentResult.structuredOutput} and on `turn`.
 	 */
 	structuredOutput?: StructuredOutputConfig
 
@@ -155,15 +171,15 @@ export interface RunAgentOptions extends AgentIdentity {
 	 * Extended-thinking request and response-effort level, forwarded on every
 	 * model call.
 	 *
-	 * These are here because the run config below is assembled by HAND, and a
+	 * These are here because the turn config below is assembled by HAND, and a
 	 * hand-listed literal silently drops whatever nobody remembered to add —
-	 * which is precisely what happened. `thinking` shipped on `AgentRunConfig`
+	 * which is precisely what happened. `thinking` shipped on the turn config
 	 * and was reachable only from the raw kernel entry point, because this
 	 * function, `ReactiveAgent` and `SupervisorAgent` each rebuilt the object
 	 * from a fixed list. So the capability existed and the front door could not
 	 * open it.
 	 *
-	 * A live run is what found it: the unit tests passed because they drove the
+	 * A live turn is what found it: the unit tests passed because they drove the
 	 * kernel directly, and a real agent run through this function put no effort
 	 * on the wire at all.
 	 */
@@ -174,7 +190,7 @@ export interface RunAgentOptions extends AgentIdentity {
 	name?: string
 
 	signal?: AbortSignal
-	listener?: RunEventListener
+	listener?: SessionEventListener
 	/** Live project policy for hosts that discover nested instruction scopes. */
 	projectInstructionContext?: ProjectInstructionContext
 }
@@ -187,17 +203,17 @@ export interface RunAgentResult {
 	 * The schema-validated answer, when {@link RunAgentOptions.structuredOutput}
 	 * asked for one and the model produced it.
 	 *
-	 * Mirrors `run.structuredOutput` the way {@link output} mirrors
-	 * `run.result` — the whole point of this shape is that the two answers a
-	 * run can give are reachable without unpacking the run.
+	 * Mirrors `turn.structuredOutput` the way {@link output} mirrors
+	 * `turn.result` — the whole point of this shape is that the two answers a
+	 * turn can give are reachable without unpacking the turn.
 	 */
 	readonly structuredOutput?: unknown
 
-	/** The full run — usage, cost, steps, stop reason, every message. */
-	readonly run: Run
+	/** The full turn — usage, cost, steps, stop reason, every message. */
+	readonly turn: Turn
 
 	/**
-	 * The identity this run used, with anything generated filled in.
+	 * The identity this turn used, with anything generated filled in.
 	 *
 	 * Pass it straight back into the next call to continue the same session.
 	 */
@@ -207,9 +223,9 @@ export interface RunAgentResult {
 /**
  * Defaults chosen to be safe rather than generous.
  *
- * A front door exists so a first run works without a decision, and the cost of
+ * A front door exists so a first turn works without a decision, and the cost of
  * that convenience is that nobody reads these numbers before their first
- * runaway loop. So: a budget that ends a stuck run in seconds rather than
+ * runaway loop. So: a budget that ends a stuck turn in seconds rather than
  * dollars, and an iteration cap that stops a tool-calling loop well before a
  * context window does. Every one is overridable and named on the option.
  */
@@ -222,14 +238,14 @@ export const DEFAULT_TIMEOUT_MS = 300_000
  *
  * `drainQuery` is the kernel's real entry point and takes eleven required
  * parameters, four of which are identity fields that throw when missing. That
- * is the correct shape for a kernel — a run with no tenant is a run no auditor
+ * is the correct shape for a kernel — a turn with no tenant is a turn no auditor
  * can attribute — and it is the wrong shape for the first thing anybody
  * writes. The proof was in this repo: the eval suites, the test files and the
  * CLI each hand-assemble the same block, which is what a missing front door
  * looks like from the inside.
  *
  * So this supplies an environment rather than a new engine. It generates the
- * identity a single-tenant local run has no opinion about, defaults the
+ * identity a single-tenant local turn has no opinion about, defaults the
  * budgets, points the working directory at the process's own, and hands back
  * both the answer and the identity it used. Everything it fills in is a normal
  * `drainQuery` parameter; there is no second code path, and a caller who
@@ -254,15 +270,19 @@ export const DEFAULT_TIMEOUT_MS = 300_000
  *   provider,
  *   model,
  *   ...first.identity,
- *   prompt: [...first.run.messages, createUserMessage('What is my name?')],
+ *   prompt: [...first.turn.messages, createUserMessage('What is my name?')],
  * })
  * ```
  */
 export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult> {
+	const workingDirectory = options.workingDirectory ?? process.cwd()
+	const layout = await resolveLayout(options, workingDirectory)
 	const identity: Required<AgentIdentity> = {
 		sessionId: options.sessionId ?? generateSessionId(),
 		topicId: options.topicId ?? generateTopicId(),
-		projectId: options.projectId ?? generateProjectId(),
+		// The working directory's project, not a minted one: a minted Project
+		// put every call in a Project of its own.
+		projectId: options.projectId ?? layout.projectId,
 		tenantId: options.tenantId ?? generateTenantId(),
 	}
 
@@ -277,11 +297,11 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 				]
 			: options.prompt
 
-	const run = await drainQuery(
+	const turn = await drainQuery(
 		{
 			provider: options.provider,
-			...(options.pathBuilder ? { pathBuilder: options.pathBuilder } : {}),
-			...(options.runStore ? { runStore: options.runStore } : {}),
+			...(layout.paths ? { paths: layout.paths } : {}),
+			...(options.sessionLog ? { sessionLog: options.sessionLog } : {}),
 			...(options.checkpointStore ? { checkpointStore: options.checkpointStore } : {}),
 			tools: options.tools ?? new ToolRegistry(),
 			...(options.toolResultGuardrails !== undefined
@@ -296,8 +316,8 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 				? { sandboxTeardownTimeoutMs: options.sandboxTeardownTimeoutMs }
 				: {}),
 			messages,
-			workingDirectory: options.workingDirectory ?? process.cwd(),
-			runConfig: {
+			workingDirectory,
+			turnConfig: {
 				model: options.model,
 				...(options.sandbox ? { sandbox: options.sandbox } : {}),
 				maxIterations: options.maxIterations ?? DEFAULT_MAX_ITERATIONS,
@@ -335,9 +355,47 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 	)
 
 	return {
-		output: run.result,
-		structuredOutput: run.structuredOutput,
-		run,
+		output: turn.result,
+		structuredOutput: turn.structuredOutput,
+		turn,
 		identity,
 	}
 }
+
+/**
+ * Where the turn is written and which project it belongs to.
+ *
+ * - A session held in memory with no `paths`: nothing on disk, and a fresh
+ *   project id unless the caller named one.
+ * - Otherwise the project the working directory stands for, found or minted
+ *   once by `ensureProject` under the given `paths.home` (or `NAMZU_HOME`),
+ *   so every turn in one directory shares a Project and its log sits beside
+ *   that project's `project.json`.
+ *
+ * A caller that passes both `paths` and a `projectId` chose both, and nothing
+ * is read. One that passes `paths` alone must name the working directory's
+ * slug: a layout pointing at a different project than the directory is
+ * refused rather than filing the turn under a project it does not belong to.
+ */
+async function resolveLayout(
+	options: Pick<RunAgentOptions, 'paths' | 'sessionLog' | 'projectId'>,
+	workingDirectory: string,
+): Promise<{ readonly paths?: SessionPaths; readonly projectId: ProjectId }> {
+	if (options.sessionLog instanceof InMemorySessionLog && options.paths === undefined) {
+		return { projectId: options.projectId ?? generateProjectId() }
+	}
+	if (options.paths && options.projectId) {
+		return { paths: options.paths, projectId: options.projectId }
+	}
+	const home = options.paths?.home ?? resolveNamzuHome()
+	const project = await ensureProject({ home, cwd: workingDirectory })
+	if (options.paths && options.paths.slug !== project.slug) {
+		throw new Error(
+			`runAgent: paths name project "${options.paths.slug}", but ${project.cwd} is project "${project.slug}". Pass projectId to file the turn under paths of your own.`,
+		)
+	}
+	return {
+		paths: options.paths ?? new SessionPaths({ home, slug: project.slug }),
+		projectId: project.projectId,
+	}
+}

package/src/agents/storage.ts

@@ -0,0 +1,36 @@
+import { defaultSessionPaths } from '../runtime/query/session-storage.js'
+import { InMemorySessionLog } from '../store/session-log/index.js'
+import type { BaseAgentConfig } from '../types/agent/base.js'
+import type { ChildSessionStorage } from '../types/agent/task.js'
+
+/**
+ * What an agent tells the children it delegates to about where their
+ * sessions live.
+ *
+ * A session held in memory (an {@link InMemorySessionLog} and no `paths`)
+ * hands that choice down, with its checkpoint store when it named one, so a
+ * child does not fall back to a disk log under `NAMZU_HOME` its parent never
+ * asked for.
+ *
+ * A session on disk hands down its layout: the `paths` it named or, with no
+ * log and no `paths`, the default layout for its working directory — the one
+ * its own log resolves to. Its children's logs then nest under its session
+ * directory, with their meta documents, however deep the delegation goes.
+ *
+ * A host log of its own with no `paths` says nothing: its layout is not
+ * known, and each child resolves its own storage from its config.
+ */
+export async function childSessionStorage(
+	config: Pick<BaseAgentConfig, 'sessionLog' | 'paths' | 'checkpointStore'>,
+	workingDirectory?: string,
+): Promise<ChildSessionStorage | undefined> {
+	if (config.paths !== undefined) return { kind: 'disk', paths: config.paths }
+	if (config.sessionLog instanceof InMemorySessionLog) {
+		return {
+			kind: 'memory',
+			...(config.checkpointStore ? { checkpointStore: config.checkpointStore } : {}),
+		}
+	}
+	if (config.sessionLog !== undefined) return undefined
+	return { kind: 'disk', paths: await defaultSessionPaths(workingDirectory) }
+}

package/src/authorization/command-line.ts

@@ -17,7 +17,7 @@
  *     true; git push origin main         -> did not match
  *     bash -c "git push origin main"     -> did not match
  *
- * A rule that fails to match reaches the permission mode, and a run with no
+ * A rule that fails to match reaches the permission mode, and a turn with no
  * terminal resolves that to `auto`. So an operator's prohibition was bypassed
  * by typing four characters in front of it, in exactly the unattended case the
  * prohibition exists for. The `bash` tool's own description tells the model to

package/src/authorization/gate.ts

@@ -41,7 +41,7 @@ export function describeRule(rule: AuthorizationRule): string {
 		case 'allow_by_name':
 			return `allowed by name (${rule.toolNames.join(', ')})`
 		case 'deny_by_name':
-			return `denied by name (${rule.toolNames.join(', ')}) — this tool is refused for this run, so a different input will not change it`
+			return `denied by name (${rule.toolNames.join(', ')}) — this tool is refused for this turn, so a different input will not change it`
 		case 'allow_by_category':
 			return `allowed by category (${rule.categories.join(', ')})`
 		case 'allow_by_tier':

package/src/authorization/permission-presets.ts

@@ -23,7 +23,7 @@ import { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './p
  */
 
 export interface PermissionPreset {
-	/** Stable, and written into the run's log. */
+	/** Stable, and written into the turn's log. */
 	readonly name: string
 	/** One sentence an operator reads when choosing between them. */
 	readonly description: string
@@ -43,7 +43,7 @@ export interface PermissionPreset {
 	 *
 	 * Advisory rather than enforced: this package cannot install a handler,
 	 * and a preset that pretended to would be claiming an authority it does
-	 * not have. It is here so a host can compare it against the run's actual
+	 * not have. It is here so a host can compare it against the turn's actual
 	 * policy and so the pairing is written down in one place instead of
 	 * living in whoever wired it.
 	 */
@@ -136,7 +136,7 @@ export const SANDBOXED_SHELL_PRESET: PermissionPreset = {
  * Nobody is watching, so the sandbox has to be.
  *
  * All three controls, because with an auto-approving policy the sandbox is
- * the ONLY boundary left. This is the preset an unattended run wants, and
+ * the ONLY boundary left. This is the preset an unattended turn wants, and
  * the one whose requirement must not be waived: the whole reason it can
  * approve everything is that the host said nothing can escape.
  */
@@ -179,7 +179,7 @@ export function permissionPreset(name: string): PermissionPreset | undefined {
  *
  * The check is the reason this function exists rather than a property
  * lookup. A host reaching for `unattended` on a `basic` tier is asking for
- * a run that approves everything with nothing enforcing the boundary it is
+ * a turn that approves everything with nothing enforcing the boundary it is
  * approving on the strength of; the answer is no, with the missing controls
  * named so the host can fix the sandbox rather than guess.
  */