@namzu/sdk 27.0.0 → 28.0.0

package/src/skills/registry.ts

@@ -1,25 +1,76 @@
+import { stat } from 'node:fs/promises'
+import { join } from 'node:path'
 import type {
 	Skill,
 	SkillChain,
 	SkillDisclosureLevel,
 	SkillLoadResult,
 } from '../types/skills/index.js'
-import { getRootLogger } from '../utils/logger.js'
-import { discoverSkills, loadSkill } from './loader.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
 
-const logger = getRootLogger().child({ component: 'SkillRegistry' })
+import { SKILL_FILENAME, discoverSkills, loadSkill } from './loader.js'
+
+/**
+ * What the file looked like when we read it.
+ *
+ * mtime AND size, not mtime alone. Coarse-grained filesystem timestamps —
+ * one-second resolution is still common on network mounts, and some
+ * container layers are worse — make two edits within one tick
+ * indistinguishable by mtime. Size catches most of what mtime misses, and
+ * the remainder is stated rather than papered over: an edit that changes
+ * neither, inside one timestamp tick, is not detected. Hashing the file
+ * would catch it and would mean reading every skill on every lookup, which
+ * is the cost this check exists to avoid.
+ */
+interface FileStamp {
+	readonly path: string
+	readonly mtimeMs: number
+	readonly size: number
+}
 
 export class SkillRegistry {
 	private skills = new Map<string, Skill>()
+	private stamps = new Map<string, FileStamp>()
+	private readonly log: Logger
+
+	/**
+	 * Bound once, at construction — not per call and not at module scope.
+	 * Per-call construction (what `register`/`registerAll` did before this)
+	 * still reads `getRootLogger()` on every call with no way for a caller to
+	 * override it; module scope is worse still, for the reason `loadSkill`
+	 * and `discoverSkills` document. A host that wants its own destination
+	 * passes `log` here once.
+	 */
+	constructor(log?: Logger) {
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'skills/registry' })
+	}
 
 	async register(dirPath: string, level: SkillDisclosureLevel = 'metadata'): Promise<Skill> {
-		const result = await loadSkill(dirPath, level)
+		const result = await loadSkill(dirPath, level, this.log)
 		this.skills.set(result.skill.metadata.name, result.skill)
+		await this.stamp(result.skill.metadata.name, dirPath)
 		return result.skill
 	}
 
+	/** Record what the file looked like, so a later read can tell it changed. */
+	private async stamp(name: string, dirPath: string): Promise<void> {
+		const path = join(dirPath, SKILL_FILENAME)
+		try {
+			const info = await stat(path)
+			this.stamps.set(name, { path, mtimeMs: info.mtimeMs, size: info.size })
+		} catch {
+			// A skill that was just read and whose file cannot now be stat'ed
+			// is a race with somebody editing it. Leaving no stamp means the
+			// next lookup treats it as changed and re-reads — which is the
+			// right answer, and strictly better than recording a stamp we
+			// could not take.
+			this.stamps.delete(name)
+		}
+	}
+
 	async registerAll(parentDir: string, level: SkillDisclosureLevel = 'metadata'): Promise<Skill[]> {
-		const dirs = await discoverSkills(parentDir)
+		const dirs = await discoverSkills(parentDir, this.log)
 		const results: Skill[] = []
 
 		for (const dir of dirs) {
@@ -27,10 +78,10 @@ export class SkillRegistry {
 			results.push(skill)
 		}
 
-		logger.debug('Registered skills from directory', {
-			parentDir,
-			count: results.length,
-			names: results.map((s) => s.metadata.name),
+		this.log.debug('Registered skills from directory', {
+			'namzu.skills.parent_dir': parentDir,
+			'namzu.skills.count': results.length,
+			'namzu.skills.names': results.map((s) => s.metadata.name),
 		})
 
 		return results
@@ -40,6 +91,53 @@ export class SkillRegistry {
 		return this.skills.get(name)
 	}
 
+	/**
+	 * Register a skill already loaded, under a name the caller chose.
+	 *
+	 * The plugin path needs this: it namespaces a plugin's skills so two
+	 * plugins shipping `reconcile` do not silently overwrite each other, and
+	 * the name a skill is filed under is then not the name in its own
+	 * frontmatter. `register(dirPath)` cannot express that.
+	 */
+	add(name: string, skill: Skill): void {
+		this.skills.set(name, skill)
+		// Deliberately NOT stamped. `add` is synchronous by contract, and a
+		// fire-and-forget `stat` here would be a promise nothing awaits
+		// racing the first `load` — sometimes stamped, sometimes not,
+		// depending on scheduling. Unstamped is treated as changed, so the
+		// first `load` re-reads: one extra read, never a stale answer, and no
+		// race to reason about.
+	}
+
+	/**
+	 * Forget one. Reports whether it was there.
+	 *
+	 * Needed by anything that can UNDO a registration — a plugin rollback,
+	 * a plugin disable. Without it a plugin that failed halfway through
+	 * enabling left its skills in the registry with nothing that could
+	 * remove them, so the model kept being offered skills from a plugin the
+	 * runtime had marked `error`.
+	 */
+	unregister(name: string): boolean {
+		this.stamps.delete(name)
+		return this.skills.delete(name)
+	}
+
+	/**
+	 * Load a skill, re-reading it if the file changed since we last did.
+	 *
+	 * The cache was permanent: once a body had been read, `existing.body`
+	 * short-circuited every later call, so an edited SKILL.md could not reach
+	 * the model without restarting the process. That is fine for a run and
+	 * wrong for a long-lived one — a skill is a file an author is editing
+	 * WHILE the agent is running, which is the whole reason it is a file and
+	 * not a constant.
+	 *
+	 * One `stat` per lookup, not a hash and not a watcher. A watcher is a
+	 * resource with a lifetime, and this registry has no teardown to hang one
+	 * on; a hash means reading every skill on every lookup, which is the cost
+	 * the cache exists to avoid.
+	 */
 	async load(
 		name: string,
 		level: SkillDisclosureLevel = 'full',
@@ -47,7 +145,21 @@ export class SkillRegistry {
 		const existing = this.skills.get(name)
 		if (!existing) return undefined
 
-		if (level === 'metadata' || existing.body) {
+		const changed = await this.hasChanged(name, existing.dirPath)
+		if (changed === 'gone') {
+			// Dropped, not served stale. A skill whose file was deleted is a
+			// skill that no longer exists, and answering with its last known
+			// body hands the model instructions for something nobody can point
+			// at. Removing the name keeps the manifest and this lookup
+			// agreeing, which they would not if one listed it and the other
+			// refused.
+			this.skills.delete(name)
+			this.stamps.delete(name)
+			this.log.info('Skill removed: its SKILL.md is gone', { 'namzu.skill.name': name })
+			return undefined
+		}
+
+		if (changed === 'same' && (level === 'metadata' || existing.body)) {
 			return {
 				skill: existing,
 				disclosureLevel: existing.body ? 'full' : 'metadata',
@@ -55,15 +167,57 @@ export class SkillRegistry {
 			}
 		}
 
-		const result = await loadSkill(existing.dirPath, level)
-		this.skills.set(name, result.skill)
-		return result
+		const result = await loadSkill(existing.dirPath, level, this.log)
+		// Keyed by the name it was REGISTERED under, not by what the reloaded
+		// file now says. The plugin path files skills under `plugin__skill`
+		// while the file says `skill`, so taking the name off disk would
+		// silently un-namespace them — the old key would point at nothing and
+		// a new one would appear that nothing in the prompt has heard of.
+		//
+		// The SAME object is stored and returned. Returning `result` while
+		// caching a re-keyed copy handed the caller the on-disk name and the
+		// registry the registered one, which is the divergence this re-keying
+		// exists to prevent, reintroduced one line below the comment saying
+		// so.
+		const rekeyed: Skill = { ...result.skill, metadata: { ...result.skill.metadata, name } }
+		this.skills.set(name, rekeyed)
+		await this.stamp(name, existing.dirPath)
+		return { ...result, skill: rekeyed }
+	}
+
+	/** `same`, `changed`, or `gone`. */
+	private async hasChanged(name: string, dirPath: string): Promise<'same' | 'changed' | 'gone'> {
+		const previous = this.stamps.get(name)
+		const path = previous?.path ?? join(dirPath, SKILL_FILENAME)
+		let info: Awaited<ReturnType<typeof stat>>
+		try {
+			info = await stat(path)
+		} catch {
+			return 'gone'
+		}
+		// Unstamped is CHANGED, not unchanged. A skill put in by `add` has no
+		// stamp, and reading it as unchanged would serve whatever the caller
+		// handed over forever — which for the plugin path is a body read at
+		// enable time and never again.
+		if (!previous) return 'changed'
+		return info.mtimeMs === previous.mtimeMs && info.size === previous.size ? 'same' : 'changed'
 	}
 
 	list(): Skill[] {
 		return [...this.skills.values()]
 	}
 
+	/**
+	 * Every registered name.
+	 *
+	 * So a lookup that misses can name what IS there. A bare "not found"
+	 * sends the model guessing at spellings, and it is guessing from a
+	 * manifest already in its own prompt.
+	 */
+	names(): readonly string[] {
+		return [...this.skills.keys()]
+	}
+
 	get size(): number {
 		return this.skills.size
 	}
@@ -77,9 +231,10 @@ export async function resolveSkillChain(
 	categorySkillsDir: string | undefined,
 	agentSkillsDir: string | undefined,
 	level: SkillDisclosureLevel = 'metadata',
+	log?: Logger,
 ): Promise<SkillChain> {
-	const categoryRegistry = new SkillRegistry()
-	const agentRegistry = new SkillRegistry()
+	const categoryRegistry = new SkillRegistry(log)
+	const agentRegistry = new SkillRegistry(log)
 
 	const inherited = categorySkillsDir
 		? await categoryRegistry.registerAll(categorySkillsDir, level)
@@ -98,11 +253,13 @@ export async function resolveSkillChain(
 
 	const resolved = [...resolvedMap.values()]
 
-	logger.debug('Resolved skill chain', {
-		inherited: inherited.map((s) => s.metadata.name),
-		own: own.map((s) => s.metadata.name),
-		resolved: resolved.map((s) => s.metadata.name),
-	})
+	resolveLogger(log)
+		.child({ [SCOPE_ATTRIBUTE]: 'skills/registry' })
+		.debug('Resolved skill chain', {
+			'namzu.skills.inherited': inherited.map((s) => s.metadata.name),
+			'namzu.skills.own': own.map((s) => s.metadata.name),
+			'namzu.skills.resolved': resolved.map((s) => s.metadata.name),
+		})
 
 	return { inherited, own, resolved }
 }

package/src/store/attachment/index.ts

@@ -0,0 +1,182 @@
+import type { Message, MessageAttachment } from '../../types/message/index.js'
+
+/**
+ * Where an attachment's bytes live when the message does not carry them.
+ *
+ * Every attachment was inline base64 on the message. That is fine for one
+ * screenshot and wrong for everything else it implies: the bytes are copied
+ * into the run's durable transcript, into every checkpoint, into every
+ * compaction pass that walks the history, and — because a conversation
+ * resends its history — into every subsequent request. A 4 MB PDF attached
+ * once is 4 MB in the transcript and 4 MB on the wire per turn for the rest
+ * of the run.
+ *
+ * So a message may carry a REFERENCE instead. The kernel treats `ref` as
+ * opaque: this seam says nothing about whether it is a hash, a path, or a
+ * URL, because the store that minted it is the only thing that can answer.
+ * A content-addressed store gets deduplication for free and this interface
+ * neither requires nor prevents that.
+ */
+
+/** An attachment whose bytes are held by a store. */
+export interface StoredAttachment {
+	readonly type: 'stored'
+	/**
+	 * Opaque to the kernel, meaningful to the store that minted it.
+	 *
+	 * Never parsed here. A ref that the kernel could interpret is a ref the
+	 * kernel could construct, and a model-authored one would then be a path
+	 * into whatever the store can reach.
+	 */
+	readonly ref: string
+	/**
+	 * What the provider is told this is.
+	 *
+	 * Declared on the message rather than read from the store, because it
+	 * decides which content block gets built and that decision has to be
+	 * makeable without a round trip. `resolveAttachment` checks it against
+	 * what the store reports and refuses a mismatch.
+	 */
+	readonly mediaType: string
+	/** Which kind of block to build once the bytes arrive. */
+	readonly kind: 'image' | 'document'
+	/** Shown to the model, for a document it can refer to by name. */
+	readonly name?: string
+	/** See {@link DocumentAttachment.citations}. Ignored for an image. */
+	readonly citations?: boolean
+}
+
+export interface StoredBytes {
+	readonly data: string
+	readonly mediaType: string
+}
+
+export interface AttachmentStore {
+	/**
+	 * Take bytes, return a ref.
+	 *
+	 * `mediaType` is stored alongside, so `get` can report what it holds and
+	 * a caller can be caught claiming something else.
+	 */
+	put(bytes: StoredBytes): Promise<string>
+	/** `undefined` for a ref this store does not hold. */
+	get(ref: string): Promise<StoredBytes | undefined>
+}
+
+/** A reference nothing could resolve. */
+export class AttachmentNotFoundError extends Error {
+	readonly details: { ref: string }
+
+	constructor(details: { ref: string }) {
+		super(`No attachment for ref "${details.ref}".`)
+		this.name = 'AttachmentNotFoundError'
+		this.details = details
+	}
+}
+
+/** A message that carries a ref, in a run with nowhere to resolve it. */
+export class NoAttachmentStoreError extends Error {
+	readonly details: { ref: string }
+
+	constructor(details: { ref: string }) {
+		super(
+			`A message carries a stored attachment ("${details.ref}") but this run has no attachment store.`,
+		)
+		this.name = 'NoAttachmentStoreError'
+		this.details = details
+	}
+}
+
+/** A store whose bytes are not what the message said they were. */
+export class AttachmentMediaTypeMismatchError extends Error {
+	readonly details: { ref: string; declared: string; stored: string }
+
+	constructor(details: { ref: string; declared: string; stored: string }) {
+		super(
+			`Attachment "${details.ref}" was declared ${details.declared} but the store holds ${details.stored}.`,
+		)
+		this.name = 'AttachmentMediaTypeMismatchError'
+		this.details = details
+	}
+}
+
+export const isStoredAttachment = (
+	attachment: MessageAttachment,
+): attachment is MessageAttachment & StoredAttachment =>
+	(attachment as { type?: string }).type === 'stored'
+
+/**
+ * Turn a stored attachment into an inline one, or refuse.
+ *
+ * Every failure here REFUSES rather than dropping the attachment. A message
+ * that quietly lost its image is a model answering a question about a
+ * picture it never saw, confidently, and nothing in the transcript says
+ * why — the worst available outcome, and the reason none of these three
+ * branches returns the message unchanged.
+ */
+export async function resolveAttachment(
+	attachment: MessageAttachment,
+	store: AttachmentStore | undefined,
+): Promise<MessageAttachment> {
+	if (!isStoredAttachment(attachment)) return attachment
+	if (!store) throw new NoAttachmentStoreError({ ref: attachment.ref })
+
+	const bytes = await store.get(attachment.ref)
+	if (!bytes) throw new AttachmentNotFoundError({ ref: attachment.ref })
+
+	if (bytes.mediaType !== attachment.mediaType) {
+		// The declared type decides which content block is built and what the
+		// provider is told the bytes are. A store holding a PDF under a ref
+		// declared `image/png` means one of the two is wrong, and guessing
+		// which sends the provider bytes it cannot read while telling it
+		// otherwise.
+		throw new AttachmentMediaTypeMismatchError({
+			ref: attachment.ref,
+			declared: attachment.mediaType,
+			stored: bytes.mediaType,
+		})
+	}
+
+	if (attachment.kind === 'document') {
+		return {
+			type: 'document',
+			data: bytes.data,
+			mediaType: bytes.mediaType,
+			...(attachment.name === undefined ? {} : { name: attachment.name }),
+			...(attachment.citations === undefined ? {} : { citations: attachment.citations }),
+		}
+	}
+	return { type: 'image', data: bytes.data, mediaType: bytes.mediaType }
+}
+
+/**
+ * Resolve every stored attachment on every message.
+ *
+ * Returns the SAME array when nothing was stored, so the common case costs
+ * one scan and no allocation — and so a caller cannot tell resolved
+ * messages from unresolved ones by identity and get it wrong.
+ */
+export async function resolveAttachments(
+	messages: readonly Message[],
+	store: AttachmentStore | undefined,
+): Promise<readonly Message[]> {
+	// `Message` rather than a structural constraint: only some members of
+	// the union carry `attachments`, and a structural bound over a union
+	// like that is not assignable in either direction. Naming the real type
+	// costs one import this module already had.
+	const has = (message: Message): readonly MessageAttachment[] | undefined =>
+		(message as { attachments?: readonly MessageAttachment[] }).attachments
+
+	if (!messages.some((m) => has(m)?.some(isStoredAttachment))) return messages
+
+	return await Promise.all(
+		messages.map(async (message) => {
+			const attachments = has(message)
+			if (!attachments?.some(isStoredAttachment)) return message
+			return {
+				...message,
+				attachments: await Promise.all(attachments.map((a) => resolveAttachment(a, store))),
+			}
+		}),
+	)
+}

package/src/store/config/index.ts

@@ -0,0 +1,74 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Where an operator's config overrides survive a process.
+ *
+ * In `store/` rather than beside the registry, and shaped like its
+ * neighbours, because the alternative is a second persistence mechanism in a
+ * tree that already has one — and two ways to write durable state is two
+ * places to get a path, a permission or an encoding wrong.
+ *
+ * **Synchronous, deliberately.** `ConfigScope.get()` is read on every
+ * reconnect attempt and inside a supervisor's backoff loop, so a config read
+ * cannot be a promise without making every consumer async for a value that
+ * is already in memory. The store is read ONCE at construction and written
+ * through on update, which is what makes that possible.
+ */
+
+export interface ConfigOverrideStore {
+	/** Everything previously written, keyed by namespace. Read once. */
+	load(): Record<string, unknown>
+	/** Persist one namespace's accumulated override. */
+	save(namespace: string, override: unknown): void
+}
+
+/** The default: nothing survives the process, and it says so by its name. */
+export class InMemoryConfigOverrideStore implements ConfigOverrideStore {
+	private readonly overrides: Record<string, unknown> = {}
+
+	load(): Record<string, unknown> {
+		return { ...this.overrides }
+	}
+
+	save(namespace: string, override: unknown): void {
+		this.overrides[namespace] = override
+	}
+}
+
+/**
+ * One JSON file, rewritten whole on every save.
+ *
+ * Whole-file rather than append-and-replay: this holds tens of small
+ * objects, not a log, and a rewrite is the shape a human can open and read.
+ * A corrupt file loads as empty rather than throwing — a config override is
+ * a preference, and refusing to start a run because one is unreadable would
+ * make a convenience into an outage.
+ */
+export class DiskConfigOverrideStore implements ConfigOverrideStore {
+	private cache: Record<string, unknown> | undefined
+
+	constructor(private readonly path: string) {}
+
+	load(): Record<string, unknown> {
+		if (this.cache) return { ...this.cache }
+		try {
+			const parsed: unknown = JSON.parse(readFileSync(this.path, 'utf-8'))
+			this.cache =
+				typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+					? (parsed as Record<string, unknown>)
+					: {}
+		} catch {
+			this.cache = {}
+		}
+		return { ...this.cache }
+	}
+
+	save(namespace: string, override: unknown): void {
+		const current = this.load()
+		current[namespace] = override
+		this.cache = current
+		mkdirSync(dirname(this.path), { recursive: true })
+		writeFileSync(this.path, `${JSON.stringify(current, null, '\t')}\n`, 'utf-8')
+	}
+}