@namzu/sdk 45.0.0 → 45.1.0

package/src/schedules/tz.ts

@@ -0,0 +1,155 @@
+/**
+ * Time-zone arithmetic over `Intl` alone.
+ *
+ * The SDK carries no time-zone database of its own: the runtime's ICU data is
+ * the source, read through `Intl.DateTimeFormat#formatToParts`. Everything in
+ * this file is expressed in "wall" milliseconds — a local date and time
+ * written as if it were UTC (`Date.UTC(y, m - 1, d, h, min)`) — so local
+ * arithmetic is plain integer arithmetic and only the conversions touch Intl.
+ */
+
+import { ScheduleValidationError } from './errors.js'
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+function formatterFor(tz: string): Intl.DateTimeFormat {
+	let f = formatters.get(tz)
+	if (!f) {
+		f = new Intl.DateTimeFormat('en-US', {
+			timeZone: tz,
+			hourCycle: 'h23',
+			year: 'numeric',
+			month: 'numeric',
+			day: 'numeric',
+			hour: 'numeric',
+			minute: 'numeric',
+			second: 'numeric',
+		})
+		formatters.set(tz, f)
+	}
+	return f
+}
+
+/**
+ * Throw unless `tz` is an IANA zone this runtime knows. Returns the zone as
+ * the runtime spells it (`europe/istanbul` → `Europe/Istanbul`).
+ */
+export function validateTimeZone(tz: string): string {
+	if (typeof tz !== 'string' || tz.trim() === '') {
+		throw new ScheduleValidationError('a time zone is required', String(tz))
+	}
+	try {
+		return new Intl.DateTimeFormat('en-US', { timeZone: tz.trim() }).resolvedOptions().timeZone
+	} catch {
+		throw new ScheduleValidationError(`unknown time zone "${tz}"`, tz)
+	}
+}
+
+/** The zone this host is in, as the runtime reports it. */
+export function hostTimeZone(): string {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+}
+
+/** The wall clock of `instant` in `tz`, as wall milliseconds (seconds dropped). */
+export function wallOf(instant: number, tz: string): number {
+	const parts = formatterFor(tz).formatToParts(new Date(instant))
+	let year = 0
+	let month = 1
+	let day = 1
+	let hour = 0
+	let minute = 0
+	for (const part of parts) {
+		switch (part.type) {
+			case 'year':
+				year = Number(part.value)
+				break
+			case 'month':
+				month = Number(part.value)
+				break
+			case 'day':
+				day = Number(part.value)
+				break
+			case 'hour':
+				hour = Number(part.value) % 24
+				break
+			case 'minute':
+				minute = Number(part.value)
+				break
+		}
+	}
+	return Date.UTC(year, month - 1, day, hour, minute)
+}
+
+/** `tz`'s offset from UTC at `instant`, in milliseconds, minute precision. */
+export function offsetAt(instant: number, tz: string): number {
+	const floored = Math.floor(instant / MINUTE) * MINUTE
+	return wallOf(floored, tz) - floored
+}
+
+/**
+ * Every instant whose wall clock in `tz` reads `wall`.
+ *
+ * One instant normally, two in the hour a fall-back repeats (earliest first),
+ * none in the hour a spring-forward skips.
+ */
+export function instantsForWall(wall: number, tz: string): number[] {
+	const offsets = new Set<number>([
+		offsetAt(wall - 26 * HOUR, tz),
+		offsetAt(wall, tz),
+		offsetAt(wall + 26 * HOUR, tz),
+	])
+	const found = new Set<number>()
+	for (const offset of offsets) {
+		const candidate = wall - offset
+		if (wallOf(candidate, tz) === wall) found.add(candidate)
+	}
+	return [...found].sort((a, b) => a - b)
+}
+
+/**
+ * The first instant whose wall clock is later than `wall`, for a `wall` that
+ * falls inside a spring-forward gap: the moment the clocks jumped.
+ */
+export function firstInstantAfterGap(wall: number, tz: string): number {
+	const a = offsetAt(wall - 26 * HOUR, tz)
+	const b = offsetAt(wall + 26 * HOUR, tz)
+	let lo = Math.floor((wall - Math.max(a, b)) / MINUTE)
+	let hi = Math.ceil((wall - Math.min(a, b)) / MINUTE)
+	// Smallest minute m in [lo, hi] with wallOf(m) > wall.
+	while (lo < hi) {
+		const mid = Math.floor((lo + hi) / 2)
+		if (wallOf(mid * MINUTE, tz) > wall) hi = mid
+		else lo = mid + 1
+	}
+	return lo * MINUTE
+}
+
+/** Civil date parts of a wall value. */
+export function civil(wall: number): {
+	year: number
+	month: number
+	day: number
+	hour: number
+	minute: number
+	weekday: number
+} {
+	const d = new Date(wall)
+	return {
+		year: d.getUTCFullYear(),
+		month: d.getUTCMonth() + 1,
+		day: d.getUTCDate(),
+		hour: d.getUTCHours(),
+		minute: d.getUTCMinutes(),
+		weekday: d.getUTCDay(),
+	}
+}
+
+/** `YYYY-MM-DD HH:MM` for an instant in `tz`. */
+export function formatWall(instant: number, tz: string): string {
+	const c = civil(wallOf(instant, tz))
+	const p = (n: number) => String(n).padStart(2, '0')
+	return `${c.year}-${p(c.month)}-${p(c.day)} ${p(c.hour)}:${p(c.minute)}`
+}

package/src/skills/index.ts

@@ -1,2 +1,2 @@
-export { loadSkill, discoverSkills } from './loader.js'
+export { SKILL_FRONTMATTER_KEYS, loadSkill, discoverSkills } from './loader.js'
 export { SkillRegistry, resolveSkillChain } from './registry.js'

package/src/skills/loader.ts

@@ -13,11 +13,38 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
 export const SKILL_FILENAME = 'SKILL.md'
 
 /**
- * `allowed-tools` may be a YAML list. The Agent Skills format writes it
- * space-separated, comma-separated or as a list, and all three must mean the
- * same grant; the reader joins a list into the comma form.
+ * The frontmatter keys this loader reads.
+ *
+ * Every other key is skipped whole, whatever YAML it is written in, so a
+ * skill written for another agent — `argument-hint: [file]`, a `hooks:`
+ * block, `user-invocable: false` — loads here with those fields ignored
+ * instead of being refused over syntax in a field nothing reads. The keys
+ * listed are still parsed strictly: a value this loader USES is never read
+ * wrongly.
+ */
+export const SKILL_FRONTMATTER_KEYS: readonly string[] = Object.freeze([
+	'name',
+	'description',
+	'license',
+	'compatibility',
+	'allowed-tools',
+	'invocation',
+	'disable-model-invocation',
+	'metadata',
+])
+
+const READS_SKILL_KEY = (key: string): boolean => SKILL_FRONTMATTER_KEYS.includes(key)
+
+/**
+ * How this loader reads frontmatter. `allowed-tools` may be a YAML list: the
+ * Agent Skills format writes it space-separated, comma-separated or as a
+ * list, and all three must mean the same grant; the reader joins a list into
+ * the comma form. Keys the loader does not read are skipped whole.
  */
-export const SKILL_FRONTMATTER_OPTIONS = { lists: ['allowed-tools'] } as const
+export const SKILL_FRONTMATTER_OPTIONS = {
+	lists: ['allowed-tools'],
+	readsKey: READS_SKILL_KEY,
+} as const
 
 /**
  * How this file's errors name themselves. Passed to the shared reader so a
@@ -110,6 +137,30 @@ function toSkillMetadata(parsed: ParsedFrontmatter, dirPath: string): SkillMetad
 		skillMetadata.invocation = invocation
 	}
 
+	// The other common spelling of "the model may not pick this":
+	// `disable-model-invocation: true` is `invocation: operator`. Read here,
+	// at the one parser, so a registry that re-reads the file on every load
+	// cannot lose it — a host-side override would be dropped by the first
+	// freshness reload and the model could then load an operator-only skill.
+	const disableModel = scalarAt(values, 'disable-model-invocation')
+	if (disableModel !== undefined) {
+		if (disableModel !== 'true' && disableModel !== 'false') {
+			// Refused for the reason `invocation` is: `yes` quietly reading as
+			// "not disabled" would put the skill back in front of the model.
+			throw new Error(
+				`${source}: disable-model-invocation must be true or false — got "${disableModel}"`,
+			)
+		}
+		if (disableModel === 'true') {
+			if (skillMetadata.invocation !== undefined && skillMetadata.invocation !== 'operator') {
+				throw new Error(
+					`${source}: disable-model-invocation: true contradicts invocation: ${skillMetadata.invocation}`,
+				)
+			}
+			skillMetadata.invocation = 'operator'
+		}
+	}
+
 	const extra = mappingAt(values, 'metadata')
 	if (extra && Object.keys(extra).length > 0) {
 		skillMetadata.metadata = { ...extra }

package/src/tools/builtins/browser-url.ts

@@ -0,0 +1,251 @@
+/**
+ * One spelling per address, decided before anyone judges the address.
+ *
+ * The browser tools' `url` and `origin` arguments are canonicalised by their
+ * input schema, and the registry hands the gate and the reviewer the schema's
+ * OUTPUT (`ToolRegistry.prepareExecution`). So a site rule written as
+ * `^https://github\.com(?:[/?#]|$)` is tested against the one spelling the
+ * browser will load, never against `HTTPS://GitHub.com:443/`,
+ * `https://github.com./` or `https://%67ithub.com/`, which name the same page
+ * and would each slip past a deny written for the plain form.
+ *
+ * The canonical form is the WHATWG URL serialisation (`new URL(x).href`),
+ * which already lowercases the scheme and host, converts an internationalised
+ * host to punycode, drops a default port, decodes percent-encoded host bytes
+ * and reads every IPv4 spelling (`2852039166`, `0xA9FEA9FE`,
+ * `0251.0376.0251.0376`, `169.254.43518`) as dotted-quad. On top of that:
+ *
+ * - trailing dots on the host are removed (`github.com.` is `github.com` to
+ *   DNS and to a person, and a different string to a pattern);
+ * - only `http:` and `https:` are accepted, plus the literal `about:blank`;
+ * - an address carrying a user name or password is refused — it is how
+ *   `https://github.com@evil.example/` reads as GitHub to a person;
+ * - cloud metadata endpoints are refused outright, in every spelling the
+ *   parser folds into them. This is a floor, not the site policy: a private
+ *   or loopback address is left to the operator's site rules, and a DNS name
+ *   that RESOLVES to a metadata address is the host's to catch after the
+ *   navigation lands.
+ */
+
+export type BrowserUrlVerdict =
+	| { readonly ok: true; readonly url: string; readonly origin: string }
+	| { readonly ok: false; readonly reason: string }
+
+export type BrowserOriginVerdict =
+	| { readonly ok: true; readonly origin: string }
+	| { readonly ok: false; readonly reason: string }
+
+/** Longest address the tools accept. Longer is not a page anyone meant to name. */
+export const BROWSER_URL_MAX_LENGTH = 8192
+
+const ABOUT_BLANK = 'about:blank'
+
+/** Host names of cloud metadata services. Compared after lowercasing and trailing-dot removal. */
+const METADATA_HOSTNAMES = new Set(['metadata.google.internal', 'metadata', 'metadata.goog'])
+
+/**
+ * IPv4 metadata endpoints: AWS, GCP, Azure, Oracle and DigitalOcean
+ * (169.254.169.254), and Alibaba Cloud (100.100.100.200).
+ */
+const METADATA_IPV4 = new Set(['169.254.169.254', '100.100.100.200'])
+
+/** IPv6 metadata endpoints, in the parser's compressed form. AWS Nitro. */
+const METADATA_IPV6 = new Set(['fd00:ec2::254'])
+
+function stripTrailingDots(hostname: string): string {
+	return hostname.replace(/\.+$/, '')
+}
+
+/** Eight hextets of a compressed IPv6 literal, or undefined if it is not one. */
+function expandIpv6(address: string): number[] | undefined {
+	const halves = address.split('::')
+	if (halves.length > 2) return undefined
+	const parse = (part: string | undefined): number[] | undefined => {
+		if (part === undefined || part === '') return []
+		const out: number[] = []
+		for (const piece of part.split(':')) {
+			if (!/^[0-9a-f]{1,4}$/.test(piece)) return undefined
+			out.push(Number.parseInt(piece, 16))
+		}
+		return out
+	}
+	const head = parse(halves[0])
+	const tail = parse(halves[1])
+	if (!head || !tail) return undefined
+	if (halves.length === 1) return head.length === 8 ? head : undefined
+	const fill = 8 - head.length - tail.length
+	if (fill < 1) return undefined
+	return [...head, ...new Array<number>(fill).fill(0), ...tail]
+}
+
+function ipv4Of(high: number, low: number): string {
+	return `${high >>> 8}.${high & 0xff}.${low >>> 8}.${low & 0xff}`
+}
+
+/**
+ * IPv4 addresses an IPv6 literal carries in a well-known embedding: mapped
+ * (`::ffff:a.b.c.d`), compatible (`::a.b.c.d`), SIIT (`::ffff:0:a.b.c.d`),
+ * NAT64 (`64:ff9b::/96`, `64:ff9b:1::/48`) and 6to4 (`2002:AABB:CCDD::`).
+ * Each is a way to reach the IPv4 address from an IPv6 spelling.
+ */
+function embeddedIpv4(h: readonly number[]): string[] {
+	const out: string[] = []
+	const zero = (from: number, to: number) => h.slice(from, to).every((x) => x === 0)
+	const last = ipv4Of(h[6] ?? 0, h[7] ?? 0)
+	if (zero(0, 5) && (h[5] === 0xffff || h[5] === 0)) out.push(last)
+	if (zero(0, 4) && h[4] === 0xffff && h[5] === 0) out.push(last)
+	if (h[0] === 0x64 && h[1] === 0xff9b) out.push(last)
+	if (h[0] === 0x2002) out.push(ipv4Of(h[1] ?? 0, h[2] ?? 0))
+	return out
+}
+
+/**
+ * Is this host a cloud metadata endpoint, in any spelling the URL parser
+ * folds into one? `hostname` is a URL's `hostname` (IPv6 in brackets) or a
+ * bare name or address.
+ */
+export function isCloudMetadataHost(hostname: string): boolean {
+	let host = stripTrailingDots(hostname.trim().toLowerCase())
+	if (host === '') return false
+	// Let the WHATWG parser fold every IPv4 and IPv6 spelling into one.
+	const bracketed = host.startsWith('[') ? host : host.includes(':') ? `[${host}]` : host
+	try {
+		host = stripTrailingDots(new URL(`http://${bracketed}/`).hostname)
+	} catch {
+		return false
+	}
+	if (METADATA_HOSTNAMES.has(host) || METADATA_IPV4.has(host)) return true
+	if (!host.startsWith('[')) return false
+	const v6 = host.slice(1, -1)
+	if (METADATA_IPV6.has(v6)) return true
+	const hextets = expandIpv6(v6)
+	if (!hextets) return false
+	return embeddedIpv4(hextets).some((v4) => METADATA_IPV4.has(v4))
+}
+
+/**
+ * The one spelling of an address the browser may be sent to, or why not.
+ *
+ * Accepts absolute `http:` and `https:` URLs and `about:blank`. See the
+ * module comment for what is folded and what is refused.
+ */
+export function canonicalizeBrowserUrl(raw: string): BrowserUrlVerdict {
+	if (typeof raw !== 'string' || raw.trim() === '')
+		return { ok: false, reason: 'the address is empty' }
+	if (raw.length > BROWSER_URL_MAX_LENGTH)
+		return { ok: false, reason: `the address is longer than ${BROWSER_URL_MAX_LENGTH} characters` }
+	let url: URL
+	try {
+		url = new URL(raw.trim())
+	} catch {
+		return {
+			ok: false,
+			reason: 'the address is not an absolute URL; give the full https:// address',
+		}
+	}
+	if (url.protocol === 'about:') {
+		if (url.pathname.toLowerCase() === 'blank' && url.search === '' && url.hash === '')
+			return { ok: true, url: ABOUT_BLANK, origin: 'null' }
+		return { ok: false, reason: 'only about:blank is allowed among about: addresses' }
+	}
+	if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+		return {
+			ok: false,
+			reason: `the scheme "${url.protocol}" is not allowed; only http and https addresses (and about:blank) can be opened`,
+		}
+	}
+	if (url.username !== '' || url.password !== '') {
+		return {
+			ok: false,
+			reason:
+				'the address carries a user name or password (user@host); credentials never go in an address — open the site and let the user sign in',
+		}
+	}
+	const host = stripTrailingDots(url.hostname)
+	if (host === '') return { ok: false, reason: 'the address has no host' }
+	if (host !== url.hostname) {
+		url.hostname = host
+		// The setter re-parses; a host that did not survive is not one to open.
+		if (stripTrailingDots(url.hostname) !== host)
+			return { ok: false, reason: 'the address host could not be canonicalised' }
+	}
+	if (isCloudMetadataHost(url.hostname)) {
+		return {
+			ok: false,
+			reason: `${url.hostname} is a cloud metadata endpoint, which the browser never opens`,
+		}
+	}
+	return { ok: true, url: url.href, origin: url.origin }
+}
+
+/**
+ * The canonical origin (`scheme://host[:port]`) a `browser_act` call names,
+ * or why it is not one. A trailing `/` is accepted; a path, query or fragment
+ * is not — the argument is an origin, copied from the snapshot header.
+ */
+export function canonicalizeBrowserOrigin(raw: string): BrowserOriginVerdict {
+	const verdict = canonicalizeBrowserUrl(raw)
+	if (!verdict.ok) return verdict
+	if (verdict.url === ABOUT_BLANK)
+		return { ok: false, reason: 'about:blank has no origin to act on; open a page first' }
+	const url = new URL(verdict.url)
+	if (url.pathname !== '/' || url.search !== '' || url.hash !== '') {
+		return {
+			ok: false,
+			reason: `"${raw}" is a URL, not an origin; copy the origin from the snapshot header (${url.origin})`,
+		}
+	}
+	return { ok: true, origin: verdict.origin }
+}
+
+export type BrowserSitePatternVerdict =
+	| { readonly ok: true; readonly pattern: string }
+	| { readonly ok: false; readonly reason: string }
+
+/**
+ * The canonical spelling of a site key an operator or a job grants —
+ * `https://github.com`, `https://*.example.com`, `http://localhost:*` — or
+ * why it is not one.
+ *
+ * The scheme is literal (`http` or `https`). The host may begin with `*.`,
+ * meaning one or more labels in front of the rest. The port may be `*`, any
+ * port; a default port is dropped. The host is lowercased and punycoded like
+ * a URL's. A bare `*`, a path, credentials and metadata hosts are refused.
+ */
+export function canonicalizeBrowserSitePattern(raw: string): BrowserSitePatternVerdict {
+	const trimmed = typeof raw === 'string' ? raw.trim() : ''
+	const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(\*\.)?([^/:?#@]+)(?::(\d{1,5}|\*))?\/?$/.exec(
+		trimmed,
+	)
+	if (!match) {
+		return {
+			ok: false,
+			reason: `"${raw}" is not a site; write scheme://host, optionally *.host and :port or :*, with no path`,
+		}
+	}
+	if ((match[3] ?? '').includes('*')) {
+		return {
+			ok: false,
+			reason: `"${raw}" has a wildcard inside the host; a wildcard may only be a leading *. before a domain`,
+		}
+	}
+	const scheme = (match[1] ?? '').toLowerCase()
+	const wildcard = match[2] !== undefined
+	const port = match[4]
+	if (scheme !== 'http' && scheme !== 'https')
+		return { ok: false, reason: `the scheme "${scheme}:" is not allowed; only http and https` }
+	const probe = canonicalizeBrowserOrigin(
+		`${scheme}://${match[3]}${port !== undefined && port !== '*' ? `:${port}` : ''}`,
+	)
+	if (!probe.ok) return { ok: false, reason: probe.reason }
+	const probeUrl = new URL(probe.origin)
+	if (
+		wildcard &&
+		(probeUrl.hostname.startsWith('[') || /^\d+(?:\.\d+){3}$/.test(probeUrl.hostname))
+	) {
+		return { ok: false, reason: 'a wildcard cannot precede an IP address' }
+	}
+	const host = `${wildcard ? '*.' : ''}${probeUrl.hostname}`
+	const portPart = port === '*' ? ':*' : probeUrl.port !== '' ? `:${probeUrl.port}` : ''
+	return { ok: true, pattern: `${scheme}://${host}${portPart}` }
+}