@namzu/sdk 0.5.0 → 1.0.0

package/src/session/workspace/__tests__/shared-run.test.ts

@@ -0,0 +1,181 @@
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { SharedRunWorkspace } from '../shared-run.js'
+
+describe('SharedRunWorkspace', () => {
+	it('creates a canonical workspace manifest with runtime-visible paths', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+			label: 'Cowork task',
+			now: new Date('2026-05-08T10:00:00.000Z'),
+		})
+
+		const manifest = await workspace.readManifest()
+		expect(manifest.kind).toBe('shared-run-workspace')
+		expect(manifest.label).toBe('Cowork task')
+		expect(manifest.paths).toMatchObject({
+			root: '/mnt/user-data/outputs/_work',
+			manifest: '/mnt/user-data/outputs/_work/manifest.json',
+			sharedContext: '/mnt/user-data/outputs/_work/02_shared_context.md',
+			sources: '/mnt/user-data/outputs/_work/sources',
+			plans: '/mnt/user-data/outputs/_work/plans',
+			agents: '/mnt/user-data/outputs/_work/agents',
+		})
+		expect(workspace.refs().supervisorBriefPath).toBe(
+			'/mnt/user-data/outputs/_work/00_supervisor_brief.md',
+		)
+		expect(workspace.refs().sharedContextPath).toBe(
+			'/mnt/user-data/outputs/_work/02_shared_context.md',
+		)
+	})
+
+	it('records source inventory and seeded supervisor brief before workers launch', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work/',
+		})
+
+		await workspace.writeSourceInventory([
+			{
+				id: 'file_abc',
+				label: 'SBD.docx',
+				path: '/mnt/user-data/uploads/file_abc/SBD.docx',
+				kind: 'docx',
+				sizeBytes: 123,
+			},
+		])
+		const briefPath = await workspace.seedSupervisorBrief({
+			briefText: 'Root task seed brief',
+		})
+		const agentPath = await workspace.registerAgentWork({
+			agentId: 'solution-architecture',
+			taskId: 'task_123',
+		})
+
+		expect(briefPath).toBe('/mnt/user-data/outputs/_work/00_supervisor_brief.md')
+		expect(agentPath).toBe('/mnt/user-data/outputs/_work/agents/solution-architecture/task_123')
+		const inventory = await readFile(join(hostRoot, 'sources', 'inventory.md'), 'utf8')
+		expect(inventory).toContain('SBD.docx')
+		expect(inventory).toContain('/mnt/user-data/uploads/file_abc/SBD.docx')
+		const manifest = await workspace.readManifest()
+		expect(manifest.sources).toHaveLength(1)
+		expect(manifest.plans[0]?.status).toBe('seeded')
+		expect(manifest.agents[0]?.workPath).toBe(agentPath)
+	})
+
+	it('preserves every agent record when workers register concurrently', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		await Promise.all(
+			Array.from({ length: 9 }, (_, index) =>
+				workspace.registerAgentWork({
+					agentId: `agent-${index + 1}`,
+					taskId: `task_${index + 1}`,
+					status: 'running',
+				}),
+			),
+		)
+
+		const manifest = await workspace.readManifest()
+		expect(manifest.agents).toHaveLength(9)
+		expect(manifest.agents.map((agent) => agent.agentId).sort()).toEqual([
+			'agent-1',
+			'agent-2',
+			'agent-3',
+			'agent-4',
+			'agent-5',
+			'agent-6',
+			'agent-7',
+			'agent-8',
+			'agent-9',
+		])
+	})
+
+	it('writes and appends per-worker briefs without losing earlier sections', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const briefPath = await workspace.writeAgentBrief({
+			agentId: 'solution-architecture',
+			taskId: 'task_abc',
+			briefText: '# Worker Brief\n\n## Assignment\n\nDraft the solution architecture section.',
+		})
+		expect(briefPath).toBe(
+			'/mnt/user-data/outputs/_work/agents/solution-architecture/task_abc/00_brief.md',
+		)
+
+		const appended = await workspace.appendAgentBrief({
+			agentId: 'solution-architecture',
+			taskId: 'task_abc',
+			sectionText:
+				'## Follow-up 2026-05-10T18:00:00.000Z\n\n### Follow-up message\n\nAdd a risks subsection.',
+		})
+		expect(appended).toBe(briefPath)
+
+		const hostBriefPath = join(
+			hostRoot,
+			'agents',
+			'solution-architecture',
+			'task_abc',
+			'00_brief.md',
+		)
+		const content = await readFile(hostBriefPath, 'utf8')
+		expect(content).toContain('Draft the solution architecture section.')
+		expect(content).toContain('Add a risks subsection.')
+		// Initial seed must precede the appended section, not the other way around.
+		const seedIndex = content.indexOf('Draft the solution architecture')
+		const followIndex = content.indexOf('Add a risks subsection.')
+		expect(seedIndex).toBeGreaterThan(-1)
+		expect(followIndex).toBeGreaterThan(seedIndex)
+	})
+
+	it('writeTaskContext stores the user request verbatim under 01_task_context.md', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const big = '# Task Context\n\n' + 'A'.repeat(40_000)
+		const path = await workspace.writeTaskContext(big)
+		expect(path).toBe('/mnt/user-data/outputs/_work/01_task_context.md')
+		expect(workspace.refs().taskContextPath).toBe(path)
+		const content = await readFile(join(hostRoot, '01_task_context.md'), 'utf8')
+		// Trailing newline added by the writer is OK; user content must not be truncated.
+		expect(content.length).toBeGreaterThanOrEqual(big.length)
+		expect(content).toContain('A'.repeat(40_000))
+	})
+
+	it('writeSharedContext stores the shared coordination packet under 02_shared_context.md', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({
+			hostRoot,
+			runtimeRoot: '/mnt/user-data/outputs/_work',
+		})
+
+		const path = await workspace.writeSharedContext('# Shared Context\n\nRead this first.')
+		expect(path).toBe('/mnt/user-data/outputs/_work/02_shared_context.md')
+		expect(workspace.refs().sharedContextPath).toBe(path)
+		const content = await readFile(join(hostRoot, '02_shared_context.md'), 'utf8')
+		expect(content).toContain('Read this first.')
+	})
+
+	it('rejects host paths that escape the shared workspace root', async () => {
+		const hostRoot = await mkdtemp(join(tmpdir(), 'namzu-shared-workspace-'))
+		const workspace = await SharedRunWorkspace.create({ hostRoot })
+
+		expect(() => workspace.hostPath('..', 'outside')).toThrow(/escapes root/)
+	})
+})

package/src/session/workspace/index.ts

@@ -24,3 +24,9 @@ export { WorkspaceBackendRegistry } from './registry.js'
 
 export { GitWorktreeDriver, parseWorktreeList } from './git-worktree.js'
 export type { ExecFile, ExecFileResult, GitWorktreeDriverConfig } from './git-worktree.js'
+
+export { SharedRunWorkspace } from './shared-run.js'
+export type {
+	RegisterSharedRunPlanInput,
+	SharedRunWorkspaceConfig,
+} from './shared-run.js'

package/src/session/workspace/shared-run.ts

@@ -0,0 +1,316 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join, normalize, relative, sep } from 'node:path'
+import { posix } from 'node:path'
+import type {
+	SharedRunWorkspaceAgentRecord,
+	SharedRunWorkspaceManifest,
+	SharedRunWorkspacePlan,
+	SharedRunWorkspaceRefs,
+	SharedRunWorkspaceSource,
+} from '../../types/workspace/shared-run.js'
+
+export interface SharedRunWorkspaceConfig {
+	/**
+	 * Host-visible `_work` directory. The runtime creates and mutates files
+	 * here before/while agents execute.
+	 */
+	hostRoot: string
+	/**
+	 * Agent-visible `_work` directory. In container sandboxes this is usually
+	 * `/mnt/user-data/outputs/_work`; in local mode it can be the same
+	 * relative path agents receive in their runtime notes.
+	 */
+	runtimeRoot?: string
+	label?: string
+	now?: Date
+}
+
+export interface RegisterSharedRunPlanInput {
+	id?: string
+	briefText: string
+	status?: SharedRunWorkspacePlan['status']
+}
+
+export class SharedRunWorkspace {
+	readonly hostRoot: string
+	readonly runtimeRoot: string
+	private manifestWriteQueue: Promise<void> = Promise.resolve()
+
+	private constructor(private readonly config: Required<SharedRunWorkspaceConfig>) {
+		this.hostRoot = config.hostRoot
+		this.runtimeRoot = trimTrailingSlash(config.runtimeRoot)
+	}
+
+	static async create(config: SharedRunWorkspaceConfig): Promise<SharedRunWorkspace> {
+		const workspace = new SharedRunWorkspace({
+			hostRoot: config.hostRoot,
+			runtimeRoot: config.runtimeRoot ?? config.hostRoot,
+			label: config.label ?? '',
+			now: config.now ?? new Date(),
+		})
+		await workspace.ensure()
+		return workspace
+	}
+
+	refs(): SharedRunWorkspaceRefs {
+		return {
+			rootPath: this.runtimePath(),
+			manifestPath: this.runtimePath('manifest.json'),
+			sharedContextPath: this.runtimePath('02_shared_context.md'),
+			sourceInventoryPath: this.runtimePath('sources', 'inventory.md'),
+			supervisorBriefPath: this.runtimePath('00_supervisor_brief.md'),
+			taskContextPath: this.runtimePath('01_task_context.md'),
+			agentsPath: this.runtimePath('agents'),
+		}
+	}
+
+	hostPath(...segments: string[]): string {
+		return safeJoin(this.hostRoot, segments)
+	}
+
+	runtimePath(...segments: string[]): string {
+		if (segments.length === 0) return this.runtimeRoot
+		return posix.join(this.runtimeRoot, ...segments.map((segment) => segment.split(sep).join('/')))
+	}
+
+	async ensure(): Promise<void> {
+		await Promise.all([
+			mkdir(this.hostPath('sources'), { recursive: true }),
+			mkdir(this.hostPath('plans', 'root'), { recursive: true }),
+			mkdir(this.hostPath('agents'), { recursive: true }),
+		])
+		await this.writeManifest((manifest) => manifest)
+	}
+
+	async readManifest(): Promise<SharedRunWorkspaceManifest> {
+		const content = await readFile(this.hostPath('manifest.json'), 'utf8').catch(() => '')
+		if (!content.trim()) return this.initialManifest()
+		return JSON.parse(content) as SharedRunWorkspaceManifest
+	}
+
+	async writeManifest(
+		update: (manifest: SharedRunWorkspaceManifest) => SharedRunWorkspaceManifest,
+	): Promise<SharedRunWorkspaceManifest> {
+		const operation = this.manifestWriteQueue
+			.catch(() => undefined)
+			.then(async () => {
+				const current = await this.readManifest().catch(() => this.initialManifest())
+				const next = update({
+					...current,
+					updatedAt: this.nowIso(),
+				})
+				await writeJsonAtomic(this.hostPath('manifest.json'), next)
+				return next
+			})
+		this.manifestWriteQueue = operation.then(
+			() => undefined,
+			() => undefined,
+		)
+		return operation
+	}
+
+	async writeSourceInventory(sources: readonly SharedRunWorkspaceSource[]): Promise<string> {
+		const lines = [
+			'# Source Inventory',
+			'',
+			sources.length
+				? 'These are the canonical input references for this run. Prefer this inventory and targeted source reads over rediscovering uploads in every worker.'
+				: 'No user-uploaded source files were registered for this run.',
+			'',
+			...sources.map((source) =>
+				[
+					`## ${source.label}`,
+					'',
+					`- id: ${source.id}`,
+					`- path: ${source.path}`,
+					source.kind ? `- kind: ${source.kind}` : null,
+					typeof source.sizeBytes === 'number' ? `- sizeBytes: ${source.sizeBytes}` : null,
+					'',
+				]
+					.filter((line): line is string => line !== null)
+					.join('\n'),
+			),
+		]
+		const content = `${lines.join('\n').trimEnd()}\n`
+		await writeFile(this.hostPath('sources', 'inventory.md'), content, 'utf8')
+		await this.writeManifest((manifest) => ({
+			...manifest,
+			sources: [...sources],
+		}))
+		return this.runtimePath('sources', 'inventory.md')
+	}
+
+	/**
+	 * Write the canonical task-context file (`_work/01_task_context.md`).
+	 * This is the single place the original user request lives in full; child
+	 * workers read this path instead of receiving the request inline in their
+	 * prompts.
+	 */
+	async writeTaskContext(text: string): Promise<string> {
+		const relativePath = ['01_task_context.md']
+		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
+		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(text), 'utf8')
+		return this.runtimePath(...relativePath)
+	}
+
+	/**
+	 * Write the shared coordination packet (`_work/02_shared_context.md`).
+	 * This is intentionally smaller and more operational than the task context:
+	 * workers read it first, then open the full task context or source inventory
+	 * only when their assignment needs raw wording or source-file details.
+	 */
+	async writeSharedContext(text: string): Promise<string> {
+		const relativePath = ['02_shared_context.md']
+		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
+		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(text), 'utf8')
+		return this.runtimePath(...relativePath)
+	}
+
+	/**
+	 * Write a per-worker brief at `agents/<agentId>/<taskId>/00_brief.md`.
+	 * Returns the runtime-visible path. Pair with `registerAgentWork` so the
+	 * agent record and the brief sit under the same scratch directory.
+	 */
+	async writeAgentBrief(input: {
+		agentId: string
+		taskId?: string
+		briefText: string
+	}): Promise<string> {
+		const taskPart = input.taskId ?? 'pending'
+		const relativePath = ['agents', input.agentId, taskPart, '00_brief.md']
+		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
+		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(input.briefText), 'utf8')
+		return this.runtimePath(...relativePath)
+	}
+
+	/**
+	 * Append a section to an existing per-worker brief, creating the file if
+	 * it doesn't yet exist. Use for follow-up turns / continue flows so the
+	 * brief stays authoritative across resumes — workers re-reading the brief
+	 * on every entry will see the latest assignment delta, not just the seed
+	 * text from initial dispatch.
+	 */
+	async appendAgentBrief(input: {
+		agentId: string
+		taskId?: string
+		sectionText: string
+	}): Promise<string> {
+		const taskPart = input.taskId ?? 'pending'
+		const relativePath = ['agents', input.agentId, taskPart, '00_brief.md']
+		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
+		const target = this.hostPath(...relativePath)
+		const existing = await readFile(target, 'utf8').catch(() => '')
+		const trimmedExisting = existing.replace(/\n*$/, '')
+		const next = trimmedExisting
+			? `${trimmedExisting}\n\n${ensureTrailingNewline(input.sectionText)}`
+			: ensureTrailingNewline(input.sectionText)
+		await writeFile(target, next, 'utf8')
+		return this.runtimePath(...relativePath)
+	}
+
+	async seedSupervisorBrief(input: RegisterSharedRunPlanInput): Promise<string> {
+		const id = input.id ?? 'root'
+		const relativePath =
+			id === 'root' ? ['00_supervisor_brief.md'] : ['plans', id, 'supervisor_brief.md']
+		await mkdir(dirnameFor(this.hostPath(...relativePath)), { recursive: true })
+		await writeFile(this.hostPath(...relativePath), ensureTrailingNewline(input.briefText), 'utf8')
+		const briefPath = this.runtimePath(...relativePath)
+		const now = this.nowIso()
+		await this.writeManifest((manifest) => ({
+			...manifest,
+			plans: upsertBy(manifest.plans, (plan) => plan.id, {
+				id,
+				briefPath,
+				status: input.status ?? 'seeded',
+				updatedAt: now,
+			}),
+		}))
+		return briefPath
+	}
+
+	async registerAgentWork(input: {
+		agentId: string
+		taskId?: string
+		status?: SharedRunWorkspaceAgentRecord['status']
+	}): Promise<string> {
+		const taskPart = input.taskId ?? 'pending'
+		const relativePath = ['agents', input.agentId, taskPart]
+		await mkdir(this.hostPath(...relativePath), { recursive: true })
+		const workPath = this.runtimePath(...relativePath)
+		const now = this.nowIso()
+		await this.writeManifest((manifest) => ({
+			...manifest,
+			agents: upsertBy(manifest.agents, (record) => `${record.agentId}:${record.taskId ?? ''}`, {
+				agentId: input.agentId,
+				...(input.taskId ? { taskId: input.taskId } : {}),
+				workPath,
+				status: input.status ?? 'assigned',
+				updatedAt: now,
+			}),
+		}))
+		return workPath
+	}
+
+	private initialManifest(): SharedRunWorkspaceManifest {
+		const now = this.config.now.toISOString()
+		return {
+			schemaVersion: 1,
+			kind: 'shared-run-workspace',
+			createdAt: now,
+			updatedAt: now,
+			...(this.config.label ? { label: this.config.label } : {}),
+			paths: {
+				root: this.runtimePath(),
+				manifest: this.runtimePath('manifest.json'),
+				sharedContext: this.runtimePath('02_shared_context.md'),
+				sources: this.runtimePath('sources'),
+				plans: this.runtimePath('plans'),
+				agents: this.runtimePath('agents'),
+			},
+			sources: [],
+			plans: [],
+			agents: [],
+		}
+	}
+
+	private nowIso(): string {
+		return new Date().toISOString()
+	}
+}
+
+function safeJoin(root: string, segments: readonly string[]): string {
+	const fullPath = normalize(join(root, ...segments))
+	const rel = relative(root, fullPath)
+	if (rel === '' || (!rel.startsWith('..') && !rel.includes(`..${sep}`))) return fullPath
+	throw new Error(`SharedRunWorkspace path escapes root: ${segments.join('/')}`)
+}
+
+function trimTrailingSlash(value: string): string {
+	if (value === '/') return value
+	return value.replace(/\/+$/, '')
+}
+
+function ensureTrailingNewline(value: string): string {
+	return value.endsWith('\n') ? value : `${value}\n`
+}
+
+async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`
+	await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+	await rename(tmpPath, path)
+}
+
+function dirnameFor(path: string): string {
+	return dirname(path)
+}
+
+function upsertBy<T>(items: readonly T[], key: (item: T) => string, next: T): T[] {
+	const nextKey = key(next)
+	let replaced = false
+	const updated = items.map((item) => {
+		if (key(item) !== nextKey) return item
+		replaced = true
+		return next
+	})
+	return replaced ? updated : [...updated, next]
+}

package/src/skills/loader.test.ts

@@ -0,0 +1,89 @@
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { discoverSkills, loadSkill } from './loader.js'
+
+async function writeSkill(parent: string, name: string, content: string): Promise<string> {
+	const dir = join(parent, name)
+	await mkdir(dir, { recursive: true })
+	await writeFile(join(dir, 'SKILL.md'), content, 'utf8')
+	return dir
+}
+
+describe('Agent Skills loader', () => {
+	it('parses standard Agent Skills frontmatter fields', async () => {
+		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
+		const dir = await writeSkill(
+			root,
+			'project-documents',
+			[
+				'---',
+				'name: project-documents',
+				'description: Draft and edit grounded project documents.',
+				'license: MIT',
+				'compatibility: Requires filesystem tools',
+				'allowed-tools: read write edit',
+				'metadata:',
+				'  owner: vandal',
+				'  version: "1.0"',
+				'---',
+				'Use grounded sources before drafting.',
+				'',
+			].join('\n'),
+		)
+
+		const result = await loadSkill(dir, 'metadata')
+
+		expect(result.skill.metadata).toEqual({
+			name: 'project-documents',
+			description: 'Draft and edit grounded project documents.',
+			license: 'MIT',
+			compatibility: 'Requires filesystem tools',
+			allowedTools: 'read write edit',
+			metadata: {
+				owner: 'vandal',
+				version: '1.0',
+			},
+		})
+		expect(result.skill.body).toBeUndefined()
+	})
+
+	it('loads the body only when the requested disclosure level is full', async () => {
+		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
+		const dir = await writeSkill(
+			root,
+			'long-form-files',
+			[
+				'---',
+				'name: long-form-files',
+				'description: Create long files with bounded edit chunks.',
+				'---',
+				'Use skeleton-first writes.',
+				'',
+			].join('\n'),
+		)
+
+		const metadataOnly = await loadSkill(dir, 'metadata')
+		const full = await loadSkill(dir, 'full')
+
+		expect(metadataOnly.skill.body).toBeUndefined()
+		expect(full.skill.body).toBe('Use skeleton-first writes.')
+	})
+
+	it('discovers one-level skill directories deterministically', async () => {
+		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
+		const a = await writeSkill(
+			root,
+			'a-skill',
+			['---', 'name: a-skill', 'description: A skill.', '---', 'A'].join('\n'),
+		)
+		const b = await writeSkill(
+			root,
+			'b-skill',
+			['---', 'name: b-skill', 'description: B skill.', '---', 'B'].join('\n'),
+		)
+
+		expect(await discoverSkills(root)).toEqual([a, b])
+	})
+})

package/src/skills/loader.ts

@@ -41,14 +41,29 @@ function parseSkillMd(raw: string, dirPath: string): ParsedSkillMd {
 function parseFlatYaml(raw: string, dirPath: string): SkillMetadata {
 	const lines = raw.split('\n')
 	const kv: Record<string, string> = {}
+	const metadata: Record<string, string> = {}
+	let section: 'metadata' | undefined
 
 	for (const line of lines) {
+		if (!line.trim() || line.trimStart().startsWith('#')) continue
+
+		if (/^\s/.test(line)) {
+			if (section !== 'metadata') continue
+			const colonIdx = line.indexOf(':')
+			if (colonIdx === -1) continue
+			const key = line.slice(0, colonIdx).trim()
+			const value = normalizeYamlScalar(line.slice(colonIdx + 1).trim())
+			if (key && value) metadata[key] = value
+			continue
+		}
+
 		const colonIdx = line.indexOf(':')
 		if (colonIdx === -1) continue
 		const key = line.slice(0, colonIdx).trim()
-		const value = line.slice(colonIdx + 1).trim()
+		const value = normalizeYamlScalar(line.slice(colonIdx + 1).trim())
 
-		kv[key] = value.replace(/^["']|["']$/g, '')
+		section = key === 'metadata' ? 'metadata' : undefined
+		if (value) kv[key] = value
 	}
 
 	if (!kv.name) {
@@ -61,19 +76,35 @@ function parseFlatYaml(raw: string, dirPath: string): SkillMetadata {
 	validateSkillName(kv.name, dirPath)
 	validateDescription(kv.description, dirPath)
 
-	const metadata: SkillMetadata = {
+	const skillMetadata: SkillMetadata = {
 		name: kv.name,
 		description: kv.description,
 	}
 
+	if (kv.license) {
+		skillMetadata.license = kv.license
+	}
+
 	if (kv.compatibility) {
 		if (kv.compatibility.length > 500) {
 			throw new Error(`SKILL.md at "${dirPath}": compatibility exceeds 500 characters`)
 		}
-		metadata.compatibility = kv.compatibility
+		skillMetadata.compatibility = kv.compatibility
+	}
+
+	if (kv['allowed-tools']) {
+		skillMetadata.allowedTools = kv['allowed-tools']
+	}
+
+	if (Object.keys(metadata).length > 0) {
+		skillMetadata.metadata = metadata
 	}
 
-	return metadata
+	return skillMetadata
+}
+
+function normalizeYamlScalar(value: string): string {
+	return value.replace(/^["']|["']$/g, '').trim()
 }
 
 const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
@@ -164,5 +195,5 @@ export async function discoverSkills(parentDir: string): Promise<string[]> {
 		logger.debug('Skills directory not found', { parentDir })
 	}
 
-	return dirs
+	return dirs.sort()
 }

package/src/streaming/coalesce.test.ts

@@ -98,7 +98,7 @@ describe('coalesce()', () => {
 				iteration: 0,
 				messageId: MID,
 				toolUseId: TUID,
-				toolName: 'Read',
+				toolName: 'read',
 			},
 			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'c' },
 		]