@namzu/sdk 43.0.0 → 44.0.0

package/src/tools/paths.ts

@@ -28,23 +28,69 @@ export function resolveWithin(root: string, candidate: string | undefined): stri
 	// different drive on Windows); a leading `..` means it climbed out.
 	if (rel.startsWith('..') || isAbsolute(rel)) {
 		throw new Error(
-			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${resolvedRoot}.`,
+			`Path escapes the working directory: ${candidate}. ${OUTSIDE_ROOTS_GUIDANCE(`inside ${resolvedRoot}`)}`,
 		)
 	}
 	return resolved
 }
 
-/** True when `candidate` resolves inside `root`. */
+/**
+ * What a refusal says after naming the path: where the tools DO reach, and
+ * how that is widened.
+ *
+ * It used to end at "Tools may only reach inside X", which reads as a wall.
+ * It is not one: a host can add a directory to the session, and a host that
+ * reviews such paths (`QueryParams.outsideRootAccess: 'review'`) turns them
+ * into an approval request before the tool ever runs, so a model that meets
+ * this text is in a turn where that did not happen. Told only "may only", a
+ * model either rewords the path forever or tells the user the file cannot be
+ * read at all; told the route, it asks for the directory.
+ */
+export const OUTSIDE_ROOTS_GUIDANCE = (reach: string): string =>
+	`This turn's file tools reach ${reach}. The boundary is the session's, not the file system's: ask the user to add the directory to the session (or approve the path, where the host asks), rather than retrying another spelling of the same path.`
+
 /**
  * The directories a tool may reach: the working directory first, then any
- * the host added for the session (`/add-dir`). Relative paths resolve
- * against the first; an absolute path is accepted inside any.
+ * the host added for the session (`/add-dir`), then any path a review
+ * approved for THIS call (`ToolContext.approvedPaths`). Relative paths
+ * resolve against the first; an absolute path is accepted inside any.
  */
 export function toolRoots(context: {
 	readonly workingDirectory: string
 	readonly additionalDirectories?: readonly string[]
+	readonly approvedPaths?: readonly string[]
 }): readonly string[] {
-	return [context.workingDirectory, ...(context.additionalDirectories ?? [])]
+	return [
+		context.workingDirectory,
+		...(context.additionalDirectories ?? []),
+		...(context.approvedPaths ?? []),
+	]
+}
+
+/**
+ * The absolute path `candidate` names when it lies outside every root, or
+ * `undefined` when a tool would accept it as it stands.
+ *
+ * Decided with {@link resolveWithinAnyReal} — the resolver the file tools
+ * run — so the review and the execution cannot disagree about which side of
+ * the boundary a path is on, symlinks included. The returned path is the
+ * lexical one, which is what {@link toolRoots} is then handed: a link inside
+ * the working directory that points outside is approved under the name the
+ * reviewer saw.
+ */
+export async function pathOutsideRoots(
+	roots: readonly string[],
+	candidate: string | undefined,
+): Promise<string | undefined> {
+	if (candidate === undefined || candidate === '') return undefined
+	const [first] = roots
+	if (first === undefined) return undefined
+	try {
+		await resolveWithinAnyReal(roots, candidate)
+		return undefined
+	} catch {
+		return resolve(resolve(first), candidate)
+	}
 }
 
 function describeRoots(roots: readonly string[]): string {
@@ -69,7 +115,7 @@ export function resolveWithinAny(roots: readonly string[], candidate: string | u
 		if (isWithin(root, resolved)) return resolveWithin(root, resolved)
 	}
 	throw new Error(
-		`Path escapes the working directory: ${candidate}. Tools may only reach ${describeRoots(roots)}.`,
+		`Path escapes the working directory: ${candidate}. ${OUTSIDE_ROOTS_GUIDANCE(describeRoots(roots))}`,
 	)
 }
 
@@ -94,7 +140,7 @@ export async function resolveWithinAnyReal(
 		}
 	}
 	throw new Error(
-		`Path escapes the working directory: ${candidate}. Tools may only reach ${describeRoots(roots)}.`,
+		`Path escapes the working directory: ${candidate}. ${OUTSIDE_ROOTS_GUIDANCE(describeRoots(roots))}`,
 		{ cause: firstError },
 	)
 }
@@ -154,37 +200,51 @@ export async function resolveWithinReal(
 	// Cheap, and the only step that can name the caller's input in its error.
 	const lexical = resolveWithin(root, candidate)
 
-	const realRoot = await realpath(root).catch(() => resolve(root))
+	// The root is canonicalized the same way as the candidate. A root that
+	// does not exist yet is not hypothetical: a reviewer approves the path a
+	// `write` is about to create (`ToolContext.approvedPaths`), and that path
+	// is then a root of its own. `realpath` on it throws, and the old fallback
+	// — the lexical root against a canonical candidate — refused the very file
+	// the user had just said yes to.
+	const realRoot = await canonicalize(resolve(root))
+	const canonical = await canonicalize(lexical)
 
+	// The whole canonical path, not only its deepest existing ancestor: for a
+	// root that exists the two agree (walking up stops at the root at the
+	// latest), and for one that does not, only the whole path can equal it.
+	// The part past the existing ancestor is lexical and cannot hide a link,
+	// because nothing is there to be one.
+	const rel = relative(realRoot, canonical)
+	if (rel.startsWith('..') || isAbsolute(rel)) {
+		throw new Error(
+			`Path escapes the working directory: ${candidate}. It resolves through a link to ${canonical}, outside ${realRoot}. ${OUTSIDE_ROOTS_GUIDANCE(`inside ${realRoot}`)}`,
+		)
+	}
+
+	return canonical
+}
+
+/**
+ * The canonical form of an absolute path that may not exist: the deepest
+ * existing ancestor with its links resolved, and the rest appended as
+ * written. A path of which nothing exists is returned as it stands.
+ */
+async function canonicalize(absolute: string): Promise<string> {
 	// Walk up to the deepest existing ancestor. Terminates at the filesystem
 	// root, where `dirname` becomes a fixed point.
-	let existing = lexical
+	let existing = absolute
 	let remainder = ''
 	for (;;) {
 		const found = await realpath(existing).then(
 			(value) => value,
 			() => undefined,
 		)
-		if (found !== undefined) {
-			existing = found
-			break
-		}
+		if (found !== undefined) return remainder ? join(found, remainder) : found
 		const parent = dirname(existing)
-		if (parent === existing) {
-			// Nothing on this branch exists at all, so there is no link to
-			// follow and the lexical answer is already the canonical one.
-			return lexical
-		}
+		// Nothing on this branch exists at all, so there is no link to follow
+		// and the lexical answer is already the canonical one.
+		if (parent === existing) return absolute
 		remainder = remainder ? join(basename(existing), remainder) : basename(existing)
 		existing = parent
 	}
-
-	const rel = relative(realRoot, existing)
-	if (rel.startsWith('..') || isAbsolute(rel)) {
-		throw new Error(
-			`Path escapes the working directory: ${candidate}. It resolves through a link to ${existing}, outside ${realRoot}.`,
-		)
-	}
-
-	return remainder ? join(existing, remainder) : existing
 }

package/src/tools/posix-path.ts

@@ -66,7 +66,7 @@ export function resolveWithinPosix(root: string, candidate: string | undefined):
 	const rel = relativePosix(root, resolved)
 	if (rel.startsWith('..')) {
 		throw new Error(
-			`Path escapes the working directory: ${candidate}. Tools may only reach inside ${root}.`,
+			`Path escapes the working directory: ${candidate}. Inside this sandbox the file tools reach only ${root}; nothing else is mounted, so no spelling of the path will be found. Ask the user to add the directory to the session (a later sandboxed turn binds it), rather than retrying.`,
 		)
 	}
 	return resolved

package/src/tools/resident-history.ts

@@ -6,7 +6,7 @@ import { defineTool } from './defineTool.js'
 /**
  * @experimental
  * Read-only tools over an explicitly authorized historical source. The host
- * resolves and checks the executing run's scope; models choose no paths,
+ * resolves and checks the executing turn's scope; models choose no paths,
  * tenant, resident, pursuit or upper-history boundary.
  */
 export function buildResidentHistoryTools(

package/src/tools/resident-tool-evidence.ts

@@ -3,7 +3,7 @@ import type { ResidentToolEvidenceSource } from '../manager/resident/tool-eviden
 import type { ToolContext, ToolDefinition } from '../types/tool/index.js'
 import { defineTool } from './defineTool.js'
 
-/** @experimental The host must authorize each executing run before returning its bound source. */
+/** @experimental The host must authorize each executing turn before returning its bound source. */
 export function buildResidentToolEvidenceTools(
 	resolveSource: (context: ToolContext) => ResidentToolEvidenceSource,
 ): ToolDefinition[] {

package/src/tools/task/create.ts

@@ -1,11 +1,14 @@
 import { z } from 'zod'
-import type { RunId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
+import type { TaskToolScope } from './index.js'
 
-export function buildTaskCreateTool(taskStore: TaskStore, runId: RunId): ToolDefinition {
+export function buildTaskCreateTool(
+	taskStore: TaskStore,
+	scope: Pick<TaskToolScope, 'sessionId' | 'turnId'>,
+): ToolDefinition {
 	return defineTool({
 		name: 'task_create',
 		description:
@@ -34,7 +37,8 @@ export function buildTaskCreateTool(taskStore: TaskStore, runId: RunId): ToolDef
 		concurrencySafe: true,
 		async execute({ subject, description, activeForm, owner, blockedBy, metadata }) {
 			const task = await taskStore.create({
-				runId,
+				sessionId: scope.sessionId,
+				turnId: scope.turnId,
 				subject,
 				description,
 				activeForm,

package/src/tools/task/index.ts

@@ -1,15 +1,31 @@
-import type { RunId } from '../../types/ids/index.js'
+import type { SessionId, TurnId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { buildTaskCreateTool } from './create.js'
 import { buildTaskListTool } from './list.js'
 import { buildTaskUpdateTool } from './update.js'
 
-export function buildTaskTools(taskStore: TaskStore, runId: RunId): ToolDefinition[] {
+/**
+ * The turn the task tools act for. Tasks are kept per session; each records
+ * the turn that created it, and the listing shows the open tasks of every
+ * turn plus those closed in this one (spec §4.5).
+ */
+export interface TaskToolScope {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/**
+	 * When the turn started (epoch milliseconds); a resumed turn passes the
+	 * time it first started. Absent: the time the tools were built.
+	 */
+	readonly turnStartedAt?: number
+}
+
+export function buildTaskTools(taskStore: TaskStore, scope: TaskToolScope): ToolDefinition[] {
+	const resolved = { ...scope, turnStartedAt: scope.turnStartedAt ?? Date.now() }
 	return [
-		buildTaskCreateTool(taskStore, runId),
+		buildTaskCreateTool(taskStore, resolved),
 		buildTaskUpdateTool(taskStore),
-		buildTaskListTool(taskStore, runId),
+		buildTaskListTool(taskStore, resolved),
 	]
 }
 

package/src/tools/task/list.ts

@@ -1,14 +1,18 @@
 import { z } from 'zod'
-import type { RunId } from '../../types/ids/index.js'
+import { selectTaskContext } from '../../store/task/context.js'
 import { type TaskStore, isTerminalTaskStatus } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import type { TaskToolScope } from './index.js'
 
-export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefinition {
+export function buildTaskListTool(
+	taskStore: TaskStore,
+	scope: TaskToolScope & { readonly turnStartedAt: number },
+): ToolDefinition {
 	return defineTool({
 		name: 'task_list',
 		description:
-			'List planning items for the current run, not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
+			'List planning items for this session: every open one, and those closed during the current turn. Not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
 		inputSchema: z.object({}),
 		category: 'custom',
 		permissions: [],
@@ -16,11 +20,13 @@ export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefin
 		destructive: false,
 		concurrencySafe: true,
 		async execute() {
-			const tasks = await taskStore.list({ runId })
-
+			const all = await taskStore.list({ sessionId: scope.sessionId })
+			// Blockers resolve against every task of the session, shown or not: a
+			// blocker closed in an earlier turn is resolved, not unknown.
 			const completedIds = new Set(
-				tasks.filter((t) => isTerminalTaskStatus(t.status)).map((t) => t.id),
+				all.filter((t) => isTerminalTaskStatus(t.status)).map((t) => t.id),
 			)
+			const tasks = selectTaskContext(all, scope)
 
 			const summary = tasks.map((task) => {
 				const unresolvedBlockers = task.blockedBy.filter((bid) => !completedIds.has(bid))

package/src/turn/LimitChecker.ts

@@ -0,0 +1,99 @@
+import type { LimitCheckerConfig, StopReason } from '../types/session/index.js'
+
+export interface LimitCheckerState {
+	aborted: boolean
+	totalTokens: number
+	totalCost: number
+	/**
+	 * Tokens accumulated at no known rate, from `CostInfo.unpricedTokens`.
+	 *
+	 * The cost checks below read `totalCost`, and `totalCost` omits whatever
+	 * these cost. Without this field they cannot tell a turn that has spent
+	 * nothing from one whose spend was never computed, so a `costLimitUsd`
+	 * silently never fires — which is what every turn did, because nothing fed
+	 * the cost calculation at all.
+	 */
+	unpricedTokens: number
+	currentIteration: number
+	startTime: number
+}
+
+export type LimitCheckResult =
+	| { type: 'ok' }
+	| { type: 'warning'; reason: StopReason }
+	| { type: 'hard_stop'; reason: StopReason }
+
+export function checkLimitsDetailed(
+	config: LimitCheckerConfig,
+	state: LimitCheckerState,
+): LimitCheckResult {
+	if (state.aborted) {
+		return { type: 'hard_stop', reason: 'cancelled' }
+	}
+
+	if (config.timeoutMs !== 0 && Date.now() - state.startTime > config.timeoutMs) {
+		return { type: 'hard_stop', reason: 'timeout' }
+	}
+
+	if (config.tokenBudget > 0 && state.totalTokens >= config.tokenBudget) {
+		return { type: 'hard_stop', reason: 'token_budget' }
+	}
+
+	if (config.costLimitUsd && config.costLimitUsd > 0) {
+		if (state.totalCost >= config.costLimitUsd) {
+			return { type: 'hard_stop', reason: 'cost_limit' }
+		}
+		// Checked BEFORE the comparison can pass, not after. `totalCost` is
+		// only the part of the turn that had a rate, so a turn whose spend is
+		// partly unknown can sit under any limit forever while spending without
+		// bound. Continuing here would be the check answering "the budget is
+		// satisfied" to the question "can the budget be evaluated?", which is
+		// the strongest available wrong answer — see
+		// "an optional dependency may not degrade a check".
+		if (state.unpricedTokens > 0) {
+			return { type: 'hard_stop', reason: 'cost_unmeasurable' }
+		}
+	}
+
+	if (config.maxIterations !== 0 && state.currentIteration >= config.maxIterations) {
+		return { type: 'hard_stop', reason: 'max_iterations' }
+	}
+
+	if (config.tokenBudget > 0) {
+		const usageRatio = state.totalTokens / config.tokenBudget
+		if (usageRatio >= config.budgetWarningThreshold) {
+			return { type: 'warning', reason: 'token_budget' }
+		}
+	}
+
+	if (config.costLimitUsd && config.costLimitUsd > 0) {
+		const costRatio = state.totalCost / config.costLimitUsd
+		if (costRatio >= config.budgetWarningThreshold) {
+			return { type: 'warning', reason: 'cost_limit' }
+		}
+	}
+
+	const timeElapsed = Date.now() - state.startTime
+	const timeRatio = timeElapsed / config.timeoutMs
+	if (config.timeoutMs > 0 && timeRatio >= config.budgetWarningThreshold) {
+		return { type: 'warning', reason: 'timeout' }
+	}
+
+	return { type: 'ok' }
+}
+
+export function buildLimitConfig(
+	tokenBudget: number,
+	timeoutMs: number,
+	costLimitUsd?: number,
+	maxIterations?: number,
+	budgetWarningThreshold?: number,
+): LimitCheckerConfig {
+	return {
+		tokenBudget,
+		timeoutMs,
+		costLimitUsd,
+		maxIterations: maxIterations ?? 200,
+		budgetWarningThreshold: budgetWarningThreshold ?? 0.9,
+	}
+}