@namzu/sdk 45.0.0 → 46.0.0

package/src/tools/schedules/types.ts

@@ -0,0 +1,265 @@
+/**
+ * The host side of the `schedule` and `session_loop` tools.
+ *
+ * The SDK holds the tool's contract with the model — its schema, its refusals
+ * and its confirmation rule — and nothing about where jobs are stored or how
+ * a confirmation is drawn. The host supplies both, and it computes every
+ * field a person is asked to confirm: the model's own words are never what
+ * the confirmation shows as fact.
+ */
+
+/** A rule effect, in the vocabulary of the CLI's `[permissions]` table. */
+export type ScheduleRuleEffect = 'allow' | 'ask' | 'deny'
+
+/** What the model proposes. Validated by the tool's schema, then by the host. */
+export interface ScheduleJobDraft {
+	readonly name: string
+	readonly prompt: string
+	/** Schedule words: `every 30m`, `0 9 * * 1-5`, `at 09:00`, `in 2h`. */
+	readonly when: string
+	/** Folder the job runs in. Absent: the session's working directory. */
+	readonly folder?: string
+	/** IANA zone for a cron expression or a local time. Absent: the host's. */
+	readonly tz?: string
+	readonly permissions: {
+		readonly preset?: 'read-only' | 'edit-in-folder'
+		/**
+		 * What happens to a call no rule covers. The model may choose `park`
+		 * (wait for the operator) or `deny`; running uncovered calls without
+		 * asking is an operator decision the tool cannot propose.
+		 */
+		readonly unmatched: 'park' | 'deny'
+		readonly execution?: 'host' | 'sandbox'
+		readonly rules?: Readonly<
+			Record<string, ScheduleRuleEffect | Readonly<Record<string, ScheduleRuleEffect>>>
+		>
+		/**
+		 * Browser access for the run. Absent: the `browser` and `browser_act`
+		 * tools are denied. Present: only the listed sites are reachable, at
+		 * the listed level, and every other site is denied — there is no
+		 * catch-all key. The tool refuses this block unless the host sets
+		 * {@link ScheduleToolHost.browserGrants}.
+		 */
+		readonly browser?: ScheduleBrowserGrant
+	}
+	readonly budget?: {
+		readonly maxIterations?: number
+		readonly tokenBudget?: number
+		readonly timeoutMs?: number
+	}
+}
+
+/**
+ * How far a scheduled run may go on one site. `read`: open and read pages,
+ * never change them. `ask`: open and change pages, each change parked for the
+ * operator. `act`: open and change pages without asking.
+ */
+export type ScheduleBrowserSiteLevel = 'read' | 'ask' | 'act'
+
+/** A scheduled job's browser grant. */
+export interface ScheduleBrowserGrant {
+	/** The browser profile the run uses; the operator's, signed in beforehand. */
+	readonly profile: string
+	/**
+	 * Canonical site key (`https://github.com`, `https://*.example.com`,
+	 * `http://localhost:*`) to level. The tool canonicalises the keys the
+	 * model wrote (see `canonicalizeBrowserSitePattern`) before the host sees
+	 * them. Unlisted sites are denied.
+	 */
+	readonly sites: Readonly<Record<string, ScheduleBrowserSiteLevel>>
+	/** Show the browser window during the run. Default: no window. */
+	readonly headed?: boolean
+}
+
+/** What the person confirming is shown. Every field is the host's own computation. */
+export interface ScheduleJobPreview {
+	readonly name: string
+	/** The canonical folder the job would run in. */
+	readonly folder: string
+	/** True when `folder` is outside the session's working directory and added directories. */
+	readonly outsideSessionRoots: boolean
+	readonly prompt: string
+	/** The schedule in words, with its zone. */
+	readonly schedule: string
+	/** The next fire times, ISO-8601 UTC. */
+	readonly nextFireTimes: readonly string[]
+	/** The permission set expanded to one line per rule, config denies included. */
+	readonly rules: readonly string[]
+	readonly unmatched: 'park' | 'deny' | 'allow'
+	readonly execution: 'host' | 'sandbox'
+	/** A rule lets the run reach the network. */
+	readonly networkAccess: boolean
+	readonly budget: {
+		readonly maxIterations: number
+		readonly tokenBudget: number
+		readonly timeoutMs: number
+	}
+	/** Runs per day at most, times the token budget. Absent for a one-shot. */
+	readonly dailyTokenCeiling?: number
+	/** Provider and model the job is pinned to. */
+	readonly model: string
+	/** Where the run's credential comes from, in words. */
+	readonly credentialSource?: string
+	/** Anything the host wants said in the warning colour. */
+	readonly warnings: readonly string[]
+}
+
+/** A job as the `list` action reports it. */
+export interface ScheduleJobSummary {
+	readonly name: string
+	readonly folder: string
+	readonly state: string
+	readonly schedule: string
+	readonly nextFireAt?: string
+	readonly lastStatus?: string
+	/** Present only for jobs in the session's own folder. */
+	readonly prompt?: string
+	/**
+	 * True for a job whose folder is the session's own. A host that lists
+	 * other folders' jobs sets it so the model can tell them apart; the tool
+	 * marks such a job `(this folder)`.
+	 */
+	readonly inSessionFolder?: boolean
+}
+
+/**
+ * What the model proposes to change in an existing job. Every field left
+ * out keeps the job's current value. `permissions`, when given, is the whole
+ * new set, with the same limits as a new job's; the host keeps the job's
+ * `execution` when it is not given, and its additional directories.
+ */
+export interface ScheduleJobChanges {
+	readonly prompt?: string
+	readonly when?: string
+	readonly folder?: string
+	readonly tz?: string
+	readonly permissions?: ScheduleJobDraft['permissions']
+	readonly budget?: ScheduleJobDraft['budget']
+}
+
+/** A proposed change to a job, as the host computed it. */
+export interface ScheduleJobUpdateProposal {
+	/** The job as it would be once changed. Every field is the host's own computation. */
+	readonly preview: ScheduleJobPreview
+	/**
+	 * What differs from the job as it stands (and from edits saved since it
+	 * was last confirmed), one line each: `- ` what goes, `+ ` what comes.
+	 */
+	readonly changes: readonly string[]
+	/** The change touches what a run may do: its rules, `unmatched`, where it runs, its browser grant. */
+	readonly permissionsChange: boolean
+}
+
+/** What the person confirming a change is shown. */
+export interface ScheduleUpdateRequest extends ScheduleJobUpdateProposal {
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool. */
+	readonly proposedBy: 'model'
+}
+
+/** What the person answered to a proposed job. */
+export type ScheduleConfirmAnswer = 'create' | 'create-paused' | 'cancel'
+
+export interface ScheduleConfirmRequest {
+	readonly preview: ScheduleJobPreview
+	/** The prompt tripwire's findings over `preview.prompt`. */
+	readonly promptFindings: readonly string[]
+	/** Always `model` from this tool: the banner says it was not the operator. */
+	readonly proposedBy: 'model'
+}
+
+export interface ScheduleToolHost {
+	/**
+	 * The host can store and enforce {@link ScheduleJobDraft.permissions}
+	 * `.browser`. Absent or false: the tool refuses a draft carrying one,
+	 * rather than let the host drop it and confirm a job the model believes
+	 * can use the browser.
+	 */
+	readonly browserGrants?: boolean
+	/** Validate the draft and compute what the person will be shown. Throws with a message on a refusal. */
+	preview(draft: ScheduleJobDraft): Promise<ScheduleJobPreview>
+	/**
+	 * Ask the person. Anything but `create` or `create-paused` — `cancel`, a
+	 * thrown error, a closed screen — means no job.
+	 *
+	 * `signal` fires when the tool's own confirmation deadline elapses or the
+	 * turn is aborted; a host that draws a screen closes it then rather than
+	 * leaving it live after the tool has given up on the answer.
+	 */
+	confirm(request: ScheduleConfirmRequest, signal?: AbortSignal): Promise<ScheduleConfirmAnswer>
+	/**
+	 * Create the job the person confirmed. `note`, when given, is appended to
+	 * what the model is told, for what the person must still do before the
+	 * job runs (install a scheduler, say): the model reports the job as set
+	 * up otherwise.
+	 */
+	create(
+		draft: ScheduleJobDraft,
+		preview: ScheduleJobPreview,
+		options: { readonly paused: boolean },
+	): Promise<{ readonly name: string; readonly note?: string }>
+	/**
+	 * Jobs, the session folder's in full, other folders' without their
+	 * prompts. `allFolders: false` lets a host list only the session
+	 * folder's; a host may list every job regardless, marking the session
+	 * folder's with {@link ScheduleJobSummary.inSessionFolder}. The tool says
+	 * "No scheduled jobs." when this returns none, so a host that filters
+	 * says so only for its folder.
+	 */
+	list(options: { readonly allFolders: boolean }): Promise<readonly ScheduleJobSummary[]>
+	/** A job by name or id prefix, or undefined. */
+	find(job: string): Promise<ScheduleJobSummary | undefined>
+	/** Ask the person to confirm resuming or deleting a job. See `confirm` on `signal`. */
+	confirmAction(
+		job: ScheduleJobSummary,
+		action: 'resume' | 'delete',
+		signal?: AbortSignal,
+	): Promise<boolean>
+	pause(job: string): Promise<void>
+	resume(job: string): Promise<void>
+	delete(job: string): Promise<void>
+	/**
+	 * Validate a change to `job` (a name or id prefix) and compute what the
+	 * person will be shown. Throws with a message on a refusal. The tool
+	 * offers `update` only when a host has all three of `previewUpdate`,
+	 * `confirmUpdate` and `update`.
+	 */
+	previewUpdate?(job: string, changes: ScheduleJobChanges): Promise<ScheduleJobUpdateProposal>
+	/**
+	 * Ask the person whether to save the change. Anything but `true` — a
+	 * thrown error, a closed screen — changes nothing. See `confirm` on
+	 * `signal`.
+	 */
+	confirmUpdate?(request: ScheduleUpdateRequest, signal?: AbortSignal): Promise<boolean>
+	/**
+	 * Save the change the person confirmed, to the same job: its id and its
+	 * history are kept, and the confirmation is the person's. `note` as for
+	 * `create`.
+	 */
+	update?(preview: ScheduleJobPreview): Promise<{ readonly name: string; readonly note?: string }>
+}
+
+/** A prompt the session re-sends to itself on an interval. */
+export interface SessionLoop {
+	readonly id: string
+	/** The interval in words. */
+	readonly schedule: string
+	readonly prompt: string
+	readonly createdAt: string
+	readonly expiresAt?: string
+	readonly lastFiredAt?: string
+	readonly createdBy: 'operator' | 'model'
+}
+
+export interface SessionLoopHost {
+	/** Throws with a message when the interval is not usable or the loop limit is reached. */
+	create(request: {
+		readonly interval: string
+		readonly prompt: string
+		readonly createdBy: 'model'
+	}): Promise<SessionLoop>
+	list(): readonly SessionLoop[]
+	/** Stop one loop by id, or every loop with `all`. Returns how many stopped. */
+	delete(id: string): Promise<number>
+}

package/src/types/authorization/index.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import { MAX_CUSTOM_PATTERN_LENGTH } from '../../constants/authorization/index.js'
+import type { ShellDialect, ToolDefinition } from '../tool/index.js'
 
 export type GateDecision = 'allow' | 'deny' | 'review'
 
@@ -81,9 +82,69 @@ export type AuthorizationRule =
 			/** The argument key, at the top level of the tool's input. */
 			argument: string
 			pattern: string
-			decision: 'allow' | 'deny'
+			/**
+			 * `review` sends a matching call to the review policy — a person,
+			 * or the turn's mode — instead of deciding it here. It matches as
+			 * `deny` does (any segment of a command line), because it is a
+			 * restriction: a rule that asks before `git push` must also ask
+			 * before `true; git push`.
+			 */
+			decision: 'allow' | 'deny' | 'review'
 	  }
 	| { type: 'allow_by_tier'; tiers: string[] }
+	| {
+			/**
+			 * A decision the host computes in code, in its place in the list.
+			 *
+			 * A pattern is the wrong tool for a rule about what a command line
+			 * DOES: a regular expression over its text has to re-implement the
+			 * shell's quoting, and every form it misses (`$'…'`, a line
+			 * continuation, a quoted separator) is a way past the rule. A host
+			 * that needs such a rule reads the line with `lexShellCommandLine`
+			 * and decides on the words bash will pass, here.
+			 *
+			 * `decide` returns a decision, or `null` to let the next rule
+			 * decide. A `decide` that throws is read as `deny`: a rule that
+			 * could not reach a verdict must not let the call through.
+			 */
+			type: 'predicate'
+			/**
+			 * What the rule refuses or allows, in words. It is the reason the
+			 * gate reports when this rule decides, so it should tell a model
+			 * whether a different input could fare better.
+			 */
+			description: string
+			decide: AuthorizationPredicate
+			/**
+			 * The reason for THIS call, when `decide` returned a decision: what
+			 * in the input matched, and where. The gate reports it instead of
+			 * {@link description}. Absent, returning `null` or throwing, the
+			 * gate reports `description`.
+			 *
+			 * A rule that refuses on several grounds and reports one fixed
+			 * sentence leaves the model, and the person reading the refusal,
+			 * to guess which ground it was. A scheduled run's refusal listed
+			 * everything the rule protects when one word of the command had
+			 * matched.
+			 */
+			describe?: (call: AuthorizationPredicateCall) => string | null
+	  }
+
+/** The call an `AuthorizationRule` of type `predicate` is asked about. */
+export interface AuthorizationPredicateCall {
+	readonly toolName: string
+	readonly toolInput: unknown
+	readonly toolDef: ToolDefinition | undefined
+	/**
+	 * The shell a command line in this call runs in: the caller's
+	 * (`ToolCallContext.commandDialect`), or `sh` when it did not say, which
+	 * is the reading that holds whichever shell runs it.
+	 */
+	readonly commandDialect: ShellDialect
+}
+
+/** The code behind an `AuthorizationRule` of type `predicate`. */
+export type AuthorizationPredicate = (call: AuthorizationPredicateCall) => GateDecision | null
 
 const AllowReadOnlySchema = z.object({
 	type: z.literal('allow_read_only'),
@@ -121,12 +182,29 @@ const ArgumentPatternSchema = z.object({
 	// fail-open shape this rule type exists to remove.
 	argument: z.string().min(1),
 	pattern: z.string().max(MAX_CUSTOM_PATTERN_LENGTH),
-	decision: z.enum(['allow', 'deny']),
+	decision: z.enum(['allow', 'deny', 'review']),
 })
 const AllowByTierSchema = z.object({
 	type: z.literal('allow_by_tier'),
 	tiers: z.array(z.string()),
 })
+const PredicateSchema = z.object({
+	type: z.literal('predicate'),
+	// A rule that says nothing about itself produces a refusal nobody can
+	// reason about.
+	description: z.string().min(1),
+	decide: z.custom<AuthorizationPredicate>((value) => typeof value === 'function', {
+		message: 'decide must be a function',
+	}),
+	// Named here so the gate's own parse keeps it: zod strips what a schema
+	// does not name.
+	describe: z
+		.custom<(call: AuthorizationPredicateCall) => string | null>(
+			(value) => typeof value === 'function',
+			{ message: 'describe must be a function' },
+		)
+		.optional(),
+})
 
 export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	AllowReadOnlySchema,
@@ -137,6 +215,7 @@ export const AuthorizationRuleSchema = z.discriminatedUnion('type', [
 	CustomPatternSchema,
 	ArgumentPatternSchema,
 	AllowByTierSchema,
+	PredicateSchema,
 ])
 
 export const AuthorizationGateConfigSchema = z.object({