@namzu/sdk 48.1.0 → 48.3.0

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/computer-use/index.ts

@@ -30,7 +30,7 @@ export interface ComputerUseCapabilities {
 	readonly keyboard: boolean
 	readonly cursorPosition: boolean
 	readonly clipboard: boolean
-	/** Exact action subset when known. Refines the broad flags; absent retains their legacy interpretation. */
+	/** Display action subset when known. Window capture and input are a separate path. */
 	readonly supportedActions?: readonly ComputerUseAction['type'][]
 	/** Supported click buttons; absent leaves button admission to the host. */
 	readonly mouseClickButtons?: readonly MouseButton[]
@@ -50,6 +50,16 @@ export interface ComputerUseCapabilities {
 	 * offer `list_windows` or `focus_window`, even when the methods exist.
 	 */
 	readonly windows?: boolean
+	/**
+	 * The host can capture and act on one named window without sharing the
+	 * whole desktop. Requires `captureWindow` and `executeWindow`.
+	 */
+	readonly windowCapture?: boolean
+	/**
+	 * Whether scoped pixel scrolling can be delivered safely. Explicit false
+	 * refuses it before a batch starts; absent retains host-defined behavior.
+	 */
+	readonly windowScroll?: boolean
 	/**
 	 * The host implements {@link ComputerUseHost.captureRegion}. Absent or
 	 * false, `zoom` still works: the tool crops a full capture instead, which
@@ -71,12 +81,13 @@ export interface ComputerUseCapabilities {
 // ---------------------------------------------------------------------------
 // Geometry + screenshot payload
 //
-// Units, once for the whole file: every coordinate and size a host accepts or
-// returns is in PHYSICAL pixels — the pixels of the captured bitmap, not
-// logical points or DPI-scaled units. A 3440x1440 monitor at 150 % scaling is
-// 3440x1440 here. A point a host is asked to act on is relative to the
-// top-left of the display it last captured (the primary display until a host
-// offers display selection); the host adds that display's origin itself.
+// Display actions use PHYSICAL pixels, not logical points or DPI-scaled
+// units. A 3440x1440 monitor at 150 % scaling is 3440x1440 here. A point a
+// host is asked to act on is relative to the top-left of the display it last
+// captured (the primary display until a host offers display selection); the
+// host adds that display's origin itself. Window actions are the explicit
+// exception: their coordinates are pixels of captureWindow's returned PNG,
+// which the window driver may have downscaled.
 // Window and UI-element bounds are the exception and say so: they are in
 // virtual-desktop physical pixels, because a window can span displays.
 // ---------------------------------------------------------------------------
@@ -146,6 +157,45 @@ export interface WindowInfo {
 	readonly minimized: boolean
 }
 
+/** A PNG of one window. Its pixels are window-local, not display-relative. */
+export interface WindowScreenshotResult {
+	readonly data: Buffer
+	readonly mimeType: 'image/png'
+	/** Pixel size of the exact PNG returned by the host. */
+	readonly width: number
+	readonly height: number
+	readonly window: WindowInfo
+	/**
+	 * Opaque capture token. The host rejects actions after another window
+	 * capture, driver restart, session revival, or target geometry change.
+	 */
+	readonly captureId: string
+	/** A limitation of this capture, when the driver reports one. */
+	readonly captureCoverage?: string
+}
+
+/** How input is delivered to a captured window. Foreground may briefly activate it. */
+export type WindowDeliveryMode = 'background' | 'foreground'
+
+/** Window-local actions. A window-scoped mouse move is not a real OS move. */
+export type WindowInputAction =
+	| Extract<ComputerUseAction, { readonly type: 'mouse_click' | 'mouse_drag' | 'scroll' }>
+	/** Foreground delivery sends text to the verified target window. */
+	| {
+			readonly type: 'type_text'
+			readonly text: string
+			readonly delivery_mode?: WindowDeliveryMode
+	  }
+	/**
+	 * `foreground` explicitly permits the host to bring the verified target
+	 * window forward for keys its background input path cannot deliver.
+	 */
+	| {
+			readonly type: 'key'
+			readonly keys: string
+			readonly delivery_mode?: WindowDeliveryMode
+	  }
+
 /**
  * What {@link ComputerUseHost.focusWindow} achieved. Bringing a window to
  * the front is a request the operating system can refuse (Windows'
@@ -334,6 +384,14 @@ export interface ComputerUseHost {
 	 * with {@link ComputerUseCapabilities.windows}.
 	 */
 	focusWindow?(id: string): Promise<FocusWindowResult>
+	/** Capture a named window. Never silently replace a failed capture with the desktop. */
+	captureWindow?(id: string): Promise<WindowScreenshotResult>
+	/**
+	 * Act in the PNG pixel space of `captureId`. The host must verify the
+	 * capture is current and still belongs to the same process/window before
+	 * dispatching input. No implicit fallback to display input is permitted.
+	 */
+	executeWindow?(captureId: string, action: WindowInputAction): Promise<void>
 	/**
 	 * Capture one region of the current display at full physical resolution.
 	 * `rect` is display-relative physical pixels; the result's `width` and