@namzu/sdk 45.0.0 → 46.0.0

package/src/types/tool/index.ts

@@ -42,6 +42,12 @@ export interface SkillRegistryRef {
 				registeredName: string
 				description: string
 				location: string
+				/**
+				 * The skill's directory as the host reads it. Optional so a registry
+				 * written before it existed still satisfies this interface; what the
+				 * `skill` tool hands a host's `resolveModelDirectory` to map.
+				 */
+				directory?: string
 				allowedTools?: string
 				invocation?: 'model' | 'operator' | 'both'
 		  }[]
@@ -50,6 +56,7 @@ export interface SkillRegistryRef {
 					registeredName: string
 					description: string
 					location: string
+					directory?: string
 					allowedTools?: string
 					invocation?: 'model' | 'operator' | 'both'
 				}[]
@@ -715,6 +722,31 @@ export interface ToolResult {
 	 * must not lose: what its controls do, where things are, what failed.
 	 */
 	workingState?: readonly import('../../compaction/types.js').WorkingStatePin[]
+	/**
+	 * This result needs a person before the turn can go on — a sign-in page,
+	 * a CAPTCHA, a second factor, anything the model must not try to answer
+	 * itself.
+	 *
+	 * The result is committed like any other: it reaches the transcript and
+	 * the session log with the rest of its batch. Then, instead of calling
+	 * the model again, the kernel writes a checkpoint and ends the segment
+	 * with `turn_paused` carrying this value. Resuming the turn continues
+	 * from that checkpoint, and the next step is a model call that sees the
+	 * results. Inside a delegated child there is no person to hand to, so
+	 * the child's turn fails with {@link ToolHandoff.reason} instead.
+	 */
+	handoff?: ToolHandoff
+}
+
+/**
+ * A tool's request to stop the turn for a person. See {@link ToolResult.handoff}.
+ */
+export interface ToolHandoff {
+	readonly kind: 'human-required'
+	/** Operator-facing text: what the person has to do before the turn resumes. */
+	readonly reason: string
+	/** Structured facts a host can render or act on, such as an origin or a command. */
+	readonly detail?: Readonly<Record<string, string>>
 }
 
 /**
@@ -810,6 +842,23 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * the safe direction to be wrong in.
 	 */
 	pathArgument?: string
+	/**
+	 * The argument that holds an absolute URL the tool has already
+	 * canonicalised in its input schema — one spelling, no whitespace.
+	 *
+	 * Declared so an `argument_pattern` rule tests the URL whole. Without it
+	 * the rule reads every argument as a possible command line, and a URL's
+	 * query separators (`&`, `;`, `|`) cut it into "segments": an `allow` for
+	 * `^https://github\.com(?:[/?#]|$)` then declined
+	 * `https://github.com/search?q=a&type=code`, because `type=code` is not
+	 * GitHub. A `deny` or `review` is unaffected either way; only an `allow`
+	 * needed every segment to match.
+	 *
+	 * Declare it only for an argument the input schema itself canonicalises
+	 * to a URL. A free-text argument that happens to hold one keeps the
+	 * command-line reading, which is the safe direction to be wrong in.
+	 */
+	urlArgument?: string
 	/**
 	 * The boolean argument by which a call asks to run outside the turn's
 	 * sandbox, when the tool offers that at all (the shipped `bash` does).
@@ -885,6 +934,18 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	isReadOnly?(input: TInput): boolean
 	isDestructive?(input: TInput): boolean
 	isConcurrencySafe?(input: TInput): boolean
+	/**
+	 * This call sends what is on the operator's screen to the model provider:
+	 * a screenshot, the titles of the open windows, a window's accessibility
+	 * tree.
+	 *
+	 * Orthogonal to {@link isReadOnly}: a screenshot changes nothing and is
+	 * still the one read a person may want to allow before it happens. A
+	 * review policy given a consent record (`createReviewHandler`'s
+	 * `screenConsent`) asks once per session before the first such call.
+	 * Absent means the tool never does.
+	 */
+	capturesScreen?(input: TInput): boolean
 
 	/**
 	 * Opt-in ordering boundary in a direct model tool-call batch. Earlier

package/src/types/tool/presentation.ts

@@ -26,6 +26,13 @@ export type ToolCallView =
 			readonly activity?: 'exploration'
 			/** A successful result may add no information beyond the completed call row. */
 			readonly visibility?: 'hidden'
+			/**
+			 * For a result: the person declined on the tool's own screen (a
+			 * confirmation they cancelled). The call did not succeed, but
+			 * nothing failed either, so a host draws it as neither: `label` says
+			 * what did not happen ("Cancelled — nothing was saved").
+			 */
+			readonly outcome?: 'cancelled'
 	  }
 	/**
 	 * A change to a document. `path` is optional because not every diff is

package/src/utils/frontmatter.ts

@@ -132,6 +132,19 @@ export interface FrontmatterOptions {
 	 * way.
 	 */
 	readonly lists?: readonly string[]
+	/**
+	 * The keys the caller reads. When given, a top-level key it answers
+	 * `false` for is skipped whole — its value and every indented line under
+	 * it — and does not appear in the result.
+	 *
+	 * The refusals in {@link UNSUPPORTED_YAML} exist so a value the caller
+	 * USES is never read wrongly. A key nobody reads cannot be read wrongly,
+	 * and refusing the whole file over it made a skill written for another
+	 * tool (`argument-hint: [file]`, a `hooks:` block with a list in it)
+	 * unusable here for the sake of a field this kernel ignores. Absent, every
+	 * key is parsed and refused exactly as before.
+	 */
+	readonly readsKey?: (key: string) => boolean
 }
 
 export interface ParsedFrontmatter {
@@ -153,15 +166,19 @@ export interface ParsedFrontmatter {
 	readonly body: string
 }
 
+/** Optional behaviour for {@link parseFrontmatter}: the same as {@link FrontmatterOptions}. */
+export type ParseFrontmatterOptions = FrontmatterOptions
+
 /**
  * Parse a markdown file's `---` frontmatter.
  *
  * @param raw The file's full contents. LF and CRLF both parse.
  * @param source A label for error messages — a path, or a phrase naming the
  *   file. Used verbatim, so the caller controls how its own errors read.
+ * @param options See {@link FrontmatterOptions}.
  * @throws If the frontmatter is absent, unclosed, or uses YAML this reader
- *   does not implement. It never returns a partial or empty result to stand in
- *   for a file it could not read.
+ *   does not implement in a key the caller reads. It never returns a partial
+ *   or empty result to stand in for a file it could not read.
  */
 export function parseFrontmatter(
 	raw: string,
@@ -198,12 +215,15 @@ export function parseFrontmatter(
 	const blocks = new Map<string, Map<string, string>>()
 	const lists = new Map<string, string[]>()
 	let currentKey: string | undefined
+	// The current top-level key is one the caller does not read: its value
+	// and its indented lines are skipped rather than parsed or refused.
+	let skipping = false
 
 	for (const line of frontmatterRaw.split(LINE_SPLIT)) {
 		if (!line.trim() || line.trimStart().startsWith('#')) continue
 
 		if (/^\s/.test(line)) {
-			if (!currentKey) continue
+			if (!currentKey || skipping) continue
 
 			// A block sequence item. Read as a list when the caller named this
 			// key in `options.lists`; refused, not skipped, everywhere else.
@@ -254,6 +274,12 @@ export function parseFrontmatter(
 		const colonIdx = line.indexOf(':')
 		if (colonIdx === -1) continue
 		const key = line.slice(0, colonIdx).trim()
+		if (options.readsKey && !options.readsKey(key)) {
+			currentKey = key
+			skipping = true
+			continue
+		}
+		skipping = false
 		const value = normalizeScalar(line.slice(colonIdx + 1))
 
 		if (listKeys.has(key) && /^\[.*\]$/.test(value)) {

package/src/utils/id.ts

@@ -197,6 +197,20 @@ export function generateDeliverableId(): DeliverableId {
 	return generateId()
 }
 
+/**
+ * The id of a scheduled job, for a host that stores schedules (the CLI's
+ * `NAMZU_HOME/schedule/`). A plain UUIDv7 string: jobs are the host's records,
+ * not a kernel entity, so there is no branded kind for them.
+ */
+export function generateScheduleJobId(): string {
+	return uuidv7()
+}
+
+/** The id of one run of a scheduled job. See {@link generateScheduleJobId}. */
+export function generateScheduleRunId(): string {
+	return uuidv7()
+}
+
 /** Entity kinds are supplied by a typed field or storage collection. */
 export interface EntityIdByKind {
 	turn: TurnId