@namzu/sdk 48.0.0 → 48.2.0

package/src/session/retention/archive.ts

@@ -223,7 +223,7 @@ export class ArchivalManager {
 
 		// 6. Dispose the workspace (idempotent — driver contract tolerates
 		//    already-disposed refs; a missing ref is a no-op).
-		if (workspace) {
+		if (workspace && sub.workspaceRetention !== 'retain') {
 			try {
 				const driver = this.deps.workspaceRegistry.get(workspace.meta.backend)
 				await driver.dispose(workspace)

package/src/store/session/disk.ts

@@ -226,6 +226,7 @@ interface PersistedSubSession {
 	failureMode: SubSession['failureMode']
 	completionMode: SubSession['completionMode']
 	workspaceId: SubSession['workspaceId']
+	workspaceRetention?: SubSession['workspaceRetention']
 	broadcastGroupId?: string
 	summaryRef?: SubSession['summaryRef']
 	archiveRef?: SubSession['archiveRef']
@@ -1126,6 +1127,7 @@ function serializeSubSession(s: SubSession, tenantId: TenantId): PersistedSubSes
 		failureMode: s.failureMode,
 		completionMode: s.completionMode,
 		workspaceId: s.workspaceId,
+		...(s.workspaceRetention !== undefined && { workspaceRetention: s.workspaceRetention }),
 		...(s.broadcastGroupId !== undefined && { broadcastGroupId: s.broadcastGroupId }),
 		...(s.summaryRef !== undefined && { summaryRef: s.summaryRef }),
 		...(s.archiveRef !== undefined && { archiveRef: s.archiveRef }),
@@ -1146,6 +1148,7 @@ function deserializeSubSession(s: PersistedSubSession): SubSession {
 		failureMode: s.failureMode,
 		completionMode: s.completionMode,
 		workspaceId: s.workspaceId,
+		...(s.workspaceRetention !== undefined && { workspaceRetention: s.workspaceRetention }),
 		...(s.broadcastGroupId !== undefined && { broadcastGroupId: s.broadcastGroupId }),
 		...(s.summaryRef !== undefined && { summaryRef: s.summaryRef }),
 		...(s.archiveRef !== undefined && { archiveRef: s.archiveRef }),

package/src/tools/builtins/browser.ts

@@ -508,7 +508,7 @@ const HUMAN_REASON_WORDS: Record<BrowserHumanRequired['reason'], string> = {
 	'two-factor': 'a second sign-in step',
 	captcha: 'a CAPTCHA',
 	'bot-block': 'a bot check',
-	'http-auth': 'a password prompt',
+	'http-auth': 'an HTTP authentication challenge',
 	'credential-field': 'a password or one-time-code field',
 }
 
@@ -527,7 +527,7 @@ function hostErrorToResult(tool: string, error: BrowserHostError): ToolResult {
 		case 'browser_human_required': {
 			const what = HUMAN_REASON_WORDS[error.reason] ?? 'something only a person can do'
 			const how = error.loginCommand
-				? ` The user can sign in with: ${oneLine(error.loginCommand, 300)}`
+				? ` The user can ${error.reason === 'http-auth' ? 'check access' : 'sign in'} with: ${oneLine(error.loginCommand, 300)}`
 				: ''
 			const detail = {
 				origin: error.origin,

package/src/tools/schedules/schedule-tool.ts

@@ -74,20 +74,28 @@ const inputSchema = z.object({
 	folder: z
 		.string()
 		.optional()
-		.describe("create: folder to run in; leave unset for the session's unless the user named one"),
+		.describe(
+			"create: existing working directory for the job; leave unset for the session's folder when valid. The file system root, the operator's home directory, NAMZU_HOME and a folder containing NAMZU_HOME are refused. If this session is in one of those, choose an existing project subfolder and set folder explicitly",
+		),
 	tz: z
 		.string()
 		.optional()
 		.describe(
 			"create: IANA time zone; leave unset for the operator's own zone unless the user named another",
 		),
+	notifyOnFinish: z
+		.boolean()
+		.optional()
+		.describe(
+			'create/update: enable routine Namzu desktop completion notices, subject to rate limits (default true). Set false for a script that sends its own notice only when something changes; failure notices stay enabled.',
+		),
 	permissions: z
 		.object({
 			preset: z
 				.enum(['read-only', 'edit-in-folder'])
 				.optional()
 				.describe(
-					'read-only: read/glob/grep/ls only. edit-in-folder: also edit and write, bash asks',
+					'read-only: read/glob/grep/ls only; its bash deny blocks every script. edit-in-folder: also edit and write, bash asks. For a pure script, omit the preset and set rules to {} with unmatched: deny',
 				),
 			unmatched: z
 				.enum(['park', 'deny'])
@@ -120,7 +128,7 @@ const inputSchema = z.object({
 		})
 		.optional()
 		.describe(
-			'create: REQUIRED explicit permission set; there is no default. A pure script cannot use a browser grant. update: the whole new set, only when the permissions change',
+			'create: REQUIRED explicit permission set; there is no default. For a pure script, use {rules:{}, unmatched:"deny"} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script cannot use a browser grant. update: the whole new set, only when the permissions change',
 		),
 	budget: z
 		.object({
@@ -311,6 +319,7 @@ async function create(
 		...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
 		...(input.folder !== undefined ? { folder: input.folder } : {}),
 		...(input.tz !== undefined ? { tz: input.tz } : {}),
+		...(input.notifyOnFinish !== undefined ? { notifyOnFinish: input.notifyOnFinish } : {}),
 		permissions,
 		...(input.budget ? { budget: input.budget } : {}),
 	}
@@ -352,7 +361,7 @@ async function create(
 			? `Job "${created.name}" was created paused. The operator can resume it with /schedule.`
 			: runKind === 'script'
 				? `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results are recorded in its history and may arrive as a notification. It creates no session.`
-				: `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results arrive as a notification and a session.`
+				: `Job "${created.name}" was created. It runs ${preview.schedule}, with nobody watching; results are recorded in a session. Completion notices ${draft.notifyOnFinish === false ? 'are off' : 'are enabled, subject to rate limits'}.`
 	return {
 		success: true,
 		output: created.note ? `${said} ${created.note}` : said,
@@ -381,6 +390,7 @@ const CHANGEABLE = [
 	'when',
 	'folder',
 	'tz',
+	'notifyOnFinish',
 	'permissions',
 	'budget',
 	'kind',
@@ -439,6 +449,7 @@ async function update(
 		...(input.when !== undefined ? { when: input.when } : {}),
 		...(input.folder !== undefined ? { folder: input.folder } : {}),
 		...(input.tz !== undefined ? { tz: input.tz } : {}),
+		...(input.notifyOnFinish !== undefined ? { notifyOnFinish: input.notifyOnFinish } : {}),
 		...(permissions ? { permissions } : {}),
 		...(input.budget ? { budget: input.budget } : {}),
 		...(input.kind !== undefined ? { runKind: input.kind } : {}),
@@ -543,7 +554,7 @@ export function buildScheduleTools(host: ScheduleToolHost): ToolDefinition[] {
 		defineTool({
 			name: SCHEDULE_TOOL_NAME,
 			description:
-				"Manage the operator's scheduled jobs: model prompts or fixed scripts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, update, resume and delete are confirmed by the operator; pause is not. A job needs name, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). agent and script+agent also need prompt; script and script+agent also need script. A pure script has no prompt, model, agent budget, browser grant or session; set script.timeoutMs to limit it. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave every other field (folder, tz, execution, budget, headed) unset unless the user asked for it: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
+				"Manage the operator's scheduled jobs: model prompts or fixed scripts that run later in a folder, with nobody watching, under an explicit permission set. Use it only when the user asks for something to happen on a schedule. create, update, resume and delete are confirmed by the operator; pause is not. A job needs name, when and permissions (unmatched: park or deny, plus a preset, rules or a browser grant). agent and script+agent also need prompt; script and script+agent also need script. For a pure script, use permissions {rules:{},unmatched:'deny'} without a preset unless you intend deny rules: read-only denies bash and blocks every script. A pure script has no prompt, model, agent budget, browser grant or session; set script.timeoutMs to limit it. To change a job, update it with job and only the fields that change; do not delete and recreate it. Leave folder unset when the session folder is valid; home, root and NAMZU_HOME are invalid, so choose an existing project subfolder there. Leave tz, execution, budget and headed unset unless the user asked for them: the defaults are the operator's, and the confirmation marks each value you chose. Scheduled runs cannot ask questions.",
 			inputSchema,
 			category: 'custom',
 			permissions: [],

package/src/tools/schedules/types.ts

@@ -40,6 +40,8 @@ export interface ScheduleJobDraft {
 	readonly folder?: string
 	/** IANA zone for a cron expression or a local time. Absent: the host's. */
 	readonly tz?: string
+	/** Enable routine completion notices. Absent: the host's usual setting. */
+	readonly notifyOnFinish?: boolean
 	readonly permissions: {
 		readonly preset?: 'read-only' | 'edit-in-folder'
 		/**
@@ -109,6 +111,8 @@ export interface ScheduleJobPreview {
 	}
 	/** The schedule in words, with its zone. */
 	readonly schedule: string
+	/** Whether a completed run sends a Namzu desktop notice; absent for older hosts. */
+	readonly notifyOnFinish?: boolean
 	/** The next fire times, ISO-8601 UTC. */
 	readonly nextFireTimes: readonly string[]
 	/** The permission set expanded to one line per rule, config denies included. */
@@ -164,6 +168,8 @@ export interface ScheduleJobChanges {
 	readonly when?: string
 	readonly folder?: string
 	readonly tz?: string
+	/** Whether routine Namzu desktop completion notices are enabled. */
+	readonly notifyOnFinish?: boolean
 	readonly permissions?: ScheduleJobDraft['permissions']
 	readonly budget?: ScheduleJobDraft['budget']
 	/**

package/src/types/agent/scheduler.ts

@@ -3,8 +3,9 @@ import type { TaskId } from '../ids/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { CancelCause } from '../session/cancel-cause.js'
 import type { ChildSessionLifecycleEvent, SessionEventListener } from '../session/events.js'
+import type { WorkspaceRef } from '../workspace/ref.js'
 import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
-import type { AgentTaskState } from './task.js'
+import type { AgentTaskState, ChildWorkspaceRequest } from './task.js'
 
 export interface TaskHandle {
 	readonly taskId: TaskId
@@ -13,6 +14,8 @@ export interface TaskHandle {
 	readonly result?: BaseAgentResult
 	readonly createdAt: number
 	readonly completedAt?: number
+	/** The workspace assigned to an explicitly isolated child, when admitted. */
+	readonly workspace?: WorkspaceRef
 }
 
 /**
@@ -29,6 +32,8 @@ export interface TaskHandle {
 export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
 
 export interface CreateTaskOptions {
+	/** Per-task filesystem choice, forwarded to the local manager at admission. */
+	readonly workspace?: ChildWorkspaceRequest
 	/**
 	 * Revalidate host authority at actual admission, including after a capacity wait.
 	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.

package/src/types/agent/task.ts

@@ -1,6 +1,6 @@
 import type { SessionTokenBudget } from '../../store/budget/index.js'
 import type { ActorRef } from '../../types/session/actor.js'
-import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
+import type { WorkspaceBackendKind, WorkspaceRef } from '../../types/workspace/ref.js'
 import type { ResumeHandler } from '../hitl/index.js'
 import type { SessionId, TaskId, TenantId, TurnId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
@@ -19,6 +19,19 @@ export type AgentTaskState =
 	| 'rejected'
 	| 'input-required'
 
+/** Per-spawn filesystem choice. Omission preserves the manager's existing behavior. */
+export type ChildWorkspaceRequest =
+	| { readonly mode: 'shared' }
+	| {
+			readonly mode: 'isolated'
+			readonly backend: 'git-worktree'
+			readonly baseRef?: string
+			/** Relative directory within the checkout where this child starts. */
+			readonly subdirectory?: string
+			/** The existing SDK behavior is `dispose`; CLI delegates select `retain`. */
+			readonly retention?: 'dispose' | 'retain'
+	  }
+
 export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
 	return state === 'completed' || state === 'failed' || state === 'canceled' || state === 'rejected'
 }
@@ -206,6 +219,8 @@ export interface AgentTask {
 	pendingMessages: Message[]
 	createdAt: number
 	completedAt?: number
+	/** Populated after an explicitly isolated spawn is admitted. */
+	workspace?: WorkspaceRef
 
 	evictAfter?: number
 
@@ -219,6 +234,8 @@ export interface AgentTask {
  * WorkspaceRef triple atomically on every spawn.
  */
 export interface SendMessageOptions {
+	/** Explicit child filesystem policy; omitted preserves legacy backend behavior. */
+	readonly workspace?: ChildWorkspaceRequest
 	/**
 	 * Revalidate host authority before admission, including after a capacity wait.
 	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.
@@ -287,6 +304,9 @@ export interface SendMessageOptions {
 }
 
 export interface AgentManagerConfig {
+	/** When neither task workspace field is set, use the registered backend (legacy) or share cwd. */
+	workspaceDefault?: 'registered' | 'shared'
+
 	/** Reject a full parent immediately (default), or retain bounded pending task handles. */
 	capacityBehavior?: 'reject' | 'queue'
 

package/src/types/connector/mcp.ts

@@ -178,6 +178,14 @@ export interface MCPJsonRpcMessage {
 	error?: MCPJsonRpcError
 }
 
+/** A validated, bounded update from one MCP tool call. */
+export interface MCPProgressUpdate {
+	readonly progress: number
+	readonly total?: number
+	/** Server text with terminal controls removed, limited to 512 UTF-8 bytes. */
+	readonly message?: string
+}
+
 /** Authority for one MCP JSON-RPC request. */
 export interface MCPRequestOptions {
 	/**
@@ -187,6 +195,12 @@ export interface MCPRequestOptions {
 	 * waiting, not that an already-started remote side effect was rolled back.
 	 */
 	readonly signal?: AbortSignal
+	/**
+	 * Receive progress for this `tools/call` only. The client adds a unique
+	 * `_meta.progressToken` when this is supplied and stops delivery as soon as
+	 * the request completes, fails or is cancelled. Other methods ignore it.
+	 */
+	readonly onProgress?: (update: MCPProgressUpdate) => void
 	/**
 	 * Extra headers for this one request, merged over the transport's static
 	 * config headers (a collision resolves to this value) and under this same

package/src/types/session/sub-session.ts

@@ -100,6 +100,8 @@ export interface SubSession {
 	failureMode: FailureMode
 	completionMode: CompletionMode
 	workspaceId: WorkspaceId | null
+	/** Keep this delegated workspace when the child ends or its session is archived. */
+	workspaceRetention?: 'retain'
 	/**
 	 * For interventions, the immutable artifact being addressed. Chains form
 	 * a strict acyclic DAG — see session-hierarchy.md §4.5.