@roj-ai/sdk 0.1.36 → 0.2.1

package/src/plugins/shell/executor.ts

@@ -1,9 +1,9 @@
-import { resolve } from 'node:path'
+import { isAbsolute, resolve } from 'node:path'
 import type { SessionEnvironment } from '~/core/sessions/session-environment.js'
 import type { ToolError } from '~/core/tools/executor.js'
 import { Err, Ok, type Result } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
-import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
+import type { ShellGrant, ShellLimits, ShellRunner, ShellRunOptions } from '~/platform/shell.js'
 
 // ============================================================================
 // Constants
@@ -12,11 +12,12 @@ import type { ChildProcess, ProcessRunner } from '~/platform/process.js'
 const VIRTUAL_SESSION = '/home/user/session'
 const VIRTUAL_WORKSPACE = '/home/user/workspace'
 
-/** Maximum output size per stream in bytes (1 MB) */
-const MAX_OUTPUT_BYTES = 1_048_576
+/** The sandbox covers these with a tmpfs, so only what a grant mounts back exists under them. */
+const HIDDEN_ROOTS = ['/home', '/root']
 
-/** Grace period before SIGKILL after SIGTERM (ms) */
-const GRACEFUL_KILL_DELAY_MS = 5000
+function isWithin(path: string, root: string): boolean {
+	return path === root || path.startsWith(root + '/')
+}
 
 // ============================================================================
 // Shell escaping
@@ -134,6 +135,8 @@ export interface SandboxConfig {
 	network?: boolean
 	/** Paths with read-write access (default: [cwd]) */
 	writablePaths?: string[]
+	/** Resource caps for the confined command; a `null` field asks for no cap. */
+	limits?: ShellLimits
 }
 
 export interface ShellConfig {
@@ -153,100 +156,6 @@ export interface ShellConfig {
 	sandbox?: SandboxConfig
 }
 
-// ============================================================================
-// Environment
-// ============================================================================
-
-/** Safe environment variables that can be passed to child processes */
-const SAFE_ENV_VARS = ['PATH', 'HOME', 'USER', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ']
-
-function getSafeEnv(): Record<string, string> {
-	return Object.fromEntries(
-		SAFE_ENV_VARS
-			.filter(key => process.env[key])
-			.map(key => [key, process.env[key]!]),
-	)
-}
-
-// ============================================================================
-// Sandbox
-// ============================================================================
-
-export interface BwrapOptions {
-	command: string
-	cwd: string
-	sandbox: SandboxConfig
-	/** Real session directory to map into sandbox */
-	sessionDir?: string
-	/** Real workspace directory to map into sandbox */
-	workspaceDir?: string
-	/** Extra paths to bind-mount inside sandbox */
-	extraBinds?: ExtraBind[]
-}
-
-export function buildBwrapArgs(opts: BwrapOptions): string[] {
-	const { command, cwd, sandbox, extraBinds } = opts
-	const sessionDir = opts.sessionDir ? resolve(opts.sessionDir) : undefined
-	const workspaceDir = opts.workspaceDir ? resolve(opts.workspaceDir) : undefined
-
-	const args: string[] = [
-		'--ro-bind',
-		'/',
-		'/',
-		'--dev',
-		'/dev',
-		'--proc',
-		'/proc',
-		'--tmpfs',
-		'/tmp',
-	]
-
-	// Hide sensitive directories with tmpfs overlays
-	// (overrides --ro-bind / / for these paths, preventing access to user home dirs and root)
-	args.push('--tmpfs', '/home')
-	args.push('--tmpfs', '/root')
-
-	if (sessionDir) {
-		// Map real session dir to /home/user/session (read-write)
-		args.push('--bind', sessionDir, VIRTUAL_SESSION)
-	}
-
-	if (workspaceDir) {
-		// Map real workspace dir to /home/user/workspace (read-write)
-		args.push('--bind', workspaceDir, VIRTUAL_WORKSPACE)
-	}
-
-	// Extra bind mounts (e.g. git project dir for worktree support, .gitconfig)
-	for (const bind of extraBinds ?? []) {
-		args.push(bind.mode === 'ro' ? '--ro-bind' : '--bind', bind.path, bind.destPath ?? bind.path)
-	}
-
-	// Additional writable paths (legacy support)
-	for (const p of sandbox.writablePaths ?? []) {
-		args.push('--bind', p, p)
-	}
-
-	// If no sessionDir/workspaceDir mapping, fall back to making cwd writable
-	if (!sessionDir && !workspaceDir) {
-		args.push('--bind', cwd, cwd)
-	}
-
-	args.push('--unshare-all')
-
-	if (sandbox.network) {
-		args.push('--share-net')
-	}
-
-	args.push('--die-with-parent')
-
-	// Set working directory inside the namespace
-	args.push('--chdir', cwd)
-
-	args.push('/bin/sh', '-c', command)
-
-	return args
-}
-
 // ============================================================================
 // Shell Executor
 // ============================================================================
@@ -270,16 +179,17 @@ export interface ShellResult {
 
 export interface ShellExecutorDeps {
 	fs: FileSystem
-	process: ProcessRunner
+	/** Absent on a host with no shell at all — every command then fails with a clear error. */
+	shell?: ShellRunner
 }
 
 export class ShellExecutor {
 	private readonly fs: FileSystem
-	private readonly process: ProcessRunner
+	private readonly shell?: ShellRunner
 
 	constructor(private config: ShellConfig, deps: ShellExecutorDeps) {
 		this.fs = deps.fs
-		this.process = deps.process
+		this.shell = deps.shell
 	}
 
 	async execute(
@@ -301,15 +211,29 @@ export class ShellExecutor {
 		// Determine sandbox mode from config
 		const sandboxEnabled = this.config.sandboxed && this.config.sandbox?.enabled !== false
 
-		// Resolve cwd based on sandbox mode:
-		// - bwrap enabled: use virtual path (bwrap handles mapping)
-		// - sandboxed but no bwrap: agent sends virtual paths, resolve to real paths
-		// - not sandboxed: agent sends real paths, use as-is
+		const shell = this.shell
+		if (!shell) {
+			return Err({
+				message: 'This host cannot run shell commands: it has no shell.',
+				recoverable: false,
+			})
+		}
+		if (sandboxEnabled && shell.confinement === 'none') {
+			return Err({
+				message: 'This session runs commands sandboxed, but the host shell cannot confine them.',
+				recoverable: false,
+			})
+		}
+		// A `host` shell needs no grants: its filesystem holds nothing but this session.
+		const confineByPaths = sandboxEnabled && shell.confinement === 'paths'
+
+		// A sandboxed agent sends virtual paths: the shell presents them, or we resolve them here.
 		let cwd: string
 		if (sandboxEnabled) {
-			cwd = input.cwd ?? VIRTUAL_SESSION
+			const cwdResult = await this.resolveSandboxCwd(input.cwd ?? VIRTUAL_SESSION, sessionDir, workspaceDir)
+			if (!cwdResult.ok) return cwdResult
+			cwd = cwdResult.value
 		} else if (this.config.sandboxed && input.cwd) {
-			// Sandboxed env but bwrap disabled — resolve virtual paths to real paths
 			const cwdResult = await resolveAgentPath(this.fs, input.cwd, sessionDir, workspaceDir, this.config.sandboxed)
 			if (!cwdResult.ok) return cwdResult
 			cwd = cwdResult.value
@@ -333,130 +257,124 @@ export class ShellExecutor {
 			}
 		}
 
-		return new Promise<Result<ShellResult, ToolError>>((resolve) => {
-			let stdout = ''
-			let stderr = ''
-			let timedOut = false
-
-			let child: ChildProcess
-			if (sandboxEnabled) {
-				// Apply resource limits inside the sandbox
-				const timeoutSeconds = Math.ceil(timeout / 1000)
-				const sandboxCommand = `ulimit -v 524288 -f 204800 -u 64 -t ${timeoutSeconds} 2>/dev/null; ${fullCommand}`
-				const bwrapArgs = buildBwrapArgs({
-					command: sandboxCommand,
-					cwd,
-					sandbox: this.config.sandbox ?? { enabled: true },
-					sessionDir,
-					workspaceDir,
-					extraBinds: this.config.extraBinds,
-				})
-				child = this.process.spawn('bwrap', bwrapArgs, {
-					cwd: sessionDir ?? this.config.cwd,
-					env: { ...getSafeEnv(), ...this.config.env },
-					detached: true,
-				})
-			} else {
-				const shell = this.config.shell ?? (process.platform === 'win32' ? 'cmd.exe' : '/bin/sh')
-				const shellFlag = process.platform === 'win32' ? '/c' : '-c'
-
-				child = this.process.spawn(shell, [shellFlag, fullCommand], {
-					cwd,
-					env: { ...getSafeEnv(), ...this.config.env },
-					detached: true,
-				})
-			}
+		const runOptions: ShellRunOptions = {
+			command: fullCommand,
+			cwd,
+			env: this.config.env,
+			stdin: input.stdin,
+			timeoutMs: timeout,
+			shell: this.config.shell,
+		}
+		if (confineByPaths) {
+			runOptions.grants = this.grants(cwd, sessionDir, workspaceDir)
+			runOptions.network = this.config.sandbox?.network
+			runOptions.limits = this.config.sandbox?.limits
+		}
 
-			// Handle stdin
-			if (input.stdin) {
-				child.stdin?.write(input.stdin)
-				child.stdin?.end()
-			} else {
-				child.stdin?.end()
+		try {
+			const result = await shell.run(runOptions)
+			return Ok({
+				stdout: result.stdout,
+				stderr: result.stderr,
+				exitCode: result.exitCode,
+				signal: result.signal,
+				timedOut: result.timedOut,
+				durationMs: Date.now() - startTime,
+			})
+		} catch (error) {
+			const durationMs = Date.now() - startTime
+			const message = error instanceof Error ? error.message : String(error)
+			return Err({
+				message,
+				recoverable: false,
+				details: error instanceof Error && 'details' in error ? error.details : { durationMs },
+			})
+		}
+	}
+
+	/**
+	 * Keep the working directory inside what the sandbox mounts, before the host chdirs into it.
+	 * Paths under the hidden home roots exist only where a grant mounts them back; the rest of
+	 * the tree the sandbox binds read-only, so a directory there grants nothing.
+	 */
+	private async resolveSandboxCwd(
+		agentCwd: string,
+		sessionDir: string,
+		workspaceDir: string | undefined,
+	): Promise<Result<string, ToolError>> {
+		if (!isAbsolute(agentCwd)) {
+			return Err({ message: `Working directory '${agentCwd}' must be an absolute path`, recoverable: false })
+		}
+		const normalized = resolve(agentCwd)
+
+		if (isWithin(normalized, VIRTUAL_SESSION) || isWithin(normalized, VIRTUAL_WORKSPACE)) {
+			const contained = await resolveAgentPath(this.fs, normalized, sessionDir, workspaceDir, true)
+			if (!contained.ok) return contained
+			return this.requireExists(contained.value, agentCwd, normalized)
+		}
+
+		for (const root of this.boundRoots()) {
+			if (!isWithin(normalized, root.seen)) continue
+			const hostPath = resolve(root.host + normalized.slice(root.seen.length))
+			if (await checkSymlinkEscape(this.fs, hostPath, root.host)) {
+				return Err({ message: `Path '${agentCwd}' resolves outside its bind mount via symlink`, recoverable: false })
 			}
+			return this.requireExists(hostPath, agentCwd, normalized)
+		}
 
-			// Collect stdout with size cap
-			let stdoutBytes = 0
-			let stdoutTruncated = false
-			child.stdout?.on('data', (data: Buffer) => {
-				if (stdoutTruncated) return
-				const remaining = MAX_OUTPUT_BYTES - stdoutBytes
-				if (data.length > remaining) {
-					stdout += data.toString('utf-8', 0, remaining)
-					stdoutBytes = MAX_OUTPUT_BYTES
-					stdoutTruncated = true
-					stdout += '\n[stdout truncated at 1 MB]'
-				} else {
-					stdout += data.toString()
-					stdoutBytes += data.length
-				}
+		if (HIDDEN_ROOTS.some((root) => isWithin(normalized, root))) {
+			const mounted = [
+				VIRTUAL_SESSION,
+				...(workspaceDir ? [VIRTUAL_WORKSPACE] : []),
+				...this.boundRoots().map((root) => root.seen),
+			]
+			return Err({
+				message: `Path '${agentCwd}' is not mounted in this sandbox. Mounted roots: ${mounted.join(', ')}`,
+				recoverable: false,
 			})
+		}
 
-			// Collect stderr with size cap
-			let stderrBytes = 0
-			let stderrTruncated = false
-			child.stderr?.on('data', (data: Buffer) => {
-				if (stderrTruncated) return
-				const remaining = MAX_OUTPUT_BYTES - stderrBytes
-				if (data.length > remaining) {
-					stderr += data.toString('utf-8', 0, remaining)
-					stderrBytes = MAX_OUTPUT_BYTES
-					stderrTruncated = true
-					stderr += '\n[stderr truncated at 1 MB]'
-				} else {
-					stderr += data.toString()
-					stderrBytes += data.length
-				}
-			})
+		return Ok(normalized)
+	}
 
-			// Timeout handler — SIGTERM first, then SIGKILL after grace period
-			let killTimeoutId: ReturnType<typeof setTimeout> | undefined
-			const timeoutId = setTimeout(() => {
-				timedOut = true
-				try {
-					process.kill(-child.pid!, 'SIGTERM')
-				} catch {
-					child.kill('SIGTERM')
-				}
-				killTimeoutId = setTimeout(() => {
-					try {
-						process.kill(-child.pid!, 'SIGKILL')
-					} catch {
-						try {
-							child.kill('SIGKILL')
-						} catch { /* already dead */ }
-					}
-				}, GRACEFUL_KILL_DELAY_MS)
-			}, timeout)
-
-			// Process exit
-			child.on('close', (code, signal) => {
-				clearTimeout(timeoutId)
-				if (killTimeoutId) clearTimeout(killTimeoutId)
-				const durationMs = Date.now() - startTime
-
-				resolve(Ok({
-					stdout: stdout.trim(),
-					stderr: stderr.trim(),
-					exitCode: code ?? -1,
-					signal: signal ?? undefined,
-					timedOut,
-					durationMs,
-				}))
-			})
+	private async requireExists(hostPath: string, agentCwd: string, seen: string): Promise<Result<string, ToolError>> {
+		if (await this.fs.exists(hostPath)) return Ok(seen)
+		return Err({ message: `Working directory '${agentCwd}' does not exist`, recoverable: false })
+	}
 
-			// Process error
-			child.on('error', (error) => {
-				clearTimeout(timeoutId)
-				if (killTimeoutId) clearTimeout(killTimeoutId)
-				const durationMs = Date.now() - startTime
+	/** Granted roots beyond the session and workspace, as the command sees them and where the host keeps them. */
+	private boundRoots(): { seen: string; host: string }[] {
+		return [
+			...(this.config.extraBinds ?? []).map((bind) => ({ seen: resolve(bind.destPath ?? bind.path), host: resolve(bind.path) })),
+			...(this.config.sandbox?.writablePaths ?? []).map((path) => ({ seen: resolve(path), host: resolve(path) })),
+		]
+	}
 
-				resolve(Err({
-					message: `Failed to execute command: ${error.message}`,
-					recoverable: false,
-					details: { durationMs },
-				}))
-			})
-		})
+	/** Session and workspace keep their agent-visible names; everything else stays where it is. */
+	private grants(cwd: string, sessionDir: string, workspaceDir: string | undefined): ShellGrant[] {
+		const grants: ShellGrant[] = []
+
+		if (sessionDir) {
+			grants.push({ path: VIRTUAL_SESSION, source: sessionDir, mode: 'rw' })
+		}
+		if (workspaceDir) {
+			grants.push({ path: VIRTUAL_WORKSPACE, source: workspaceDir, mode: 'rw' })
+		}
+
+		// Extra binds (e.g. git project dir for worktree support, .gitconfig)
+		for (const bind of this.config.extraBinds ?? []) {
+			grants.push({ path: bind.destPath ?? bind.path, source: bind.path, mode: bind.mode })
+		}
+
+		// Additional writable paths (legacy support)
+		for (const path of this.config.sandbox?.writablePaths ?? []) {
+			grants.push({ path, mode: 'rw' })
+		}
+
+		if (!sessionDir && !workspaceDir) {
+			grants.push({ path: cwd, mode: 'rw' })
+		}
+
+		return grants
 	}
 }

package/src/plugins/shell/index.ts

@@ -3,8 +3,7 @@
  */
 
 export {
-	createRestrictedShellConfig,
-	createSafeShellConfig,
+	createSandboxedShellConfig,
 	type ExtraBind as ShellExtraBind,
 	type ShellAgentConfig,
 	shellPlugin,
@@ -12,8 +11,6 @@ export {
 } from './plugin.js'
 
 export {
-	buildBwrapArgs,
-	type BwrapOptions,
 	type ExtraBind,
 	type RunCommandInput,
 	type SandboxConfig,

package/src/plugins/shell/plugin.ts

@@ -2,6 +2,7 @@ import z from 'zod/v4'
 import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { createTool } from '~/core/tools/definition.js'
 import { Err, Ok } from '~/lib/utils/result.js'
+import type { ShellLimits } from '~/platform/shell.js'
 import { type RunCommandInput, type ShellConfig, ShellExecutor } from './executor.js'
 
 /**
@@ -39,6 +40,8 @@ export interface ShellPresetConfig {
 		network?: boolean
 		/** Paths with read-write access (default: [cwd]) */
 		writablePaths?: string[]
+		/** Resource caps for the confined command; a `null` field asks for no cap. */
+		limits?: ShellLimits
 	}
 	/** Default enabled state for agents (default: true). Agents can override via ShellAgentConfig.enabled. */
 	defaultEnabled?: boolean
@@ -76,7 +79,7 @@ export const shellPlugin = definePlugin('shell')
 			extraBinds: pluginConfig.extraBinds,
 			sandbox: pluginConfig.sandbox,
 		}
-		const executor = new ShellExecutor(shellConfig, { fs: ctx.platform.fs, process: ctx.platform.process })
+		const executor = new ShellExecutor(shellConfig, { fs: ctx.platform.fs, shell: ctx.platform.shell })
 		return { executor }
 	})
 	.agentConfig<ShellAgentConfig>()
@@ -107,12 +110,7 @@ export const shellPlugin = definePlugin('shell')
 	})
 	.build()
 
-/** Safe shell config for typical development tasks */
-export function createSafeShellConfig(cwd: string): ShellPresetConfig {
-	return { cwd, timeout: 60000, sandbox: { enabled: true } }
-}
-
-/** Restrictive shell config for untrusted agents */
-export function createRestrictedShellConfig(cwd: string): ShellPresetConfig {
-	return { cwd, timeout: 30000, sandbox: { enabled: true } }
+/** Sandboxed shell config; the command timeout is the only knob it sets. */
+export function createSandboxedShellConfig(cwd: string, timeout = 60000): ShellPresetConfig {
+	return { cwd, timeout, sandbox: { enabled: true } }
 }

package/src/plugins/skills/discovery.ts

@@ -21,6 +21,7 @@
  */
 
 import * as path from 'node:path'
+import { readTextFilesOrUndefined } from '~/lib/utils/fs-batch.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err, Ok } from '~/lib/utils/result.js'
 import type { FileSystem } from '~/platform/fs.js'
@@ -200,16 +201,17 @@ export async function discoverSkills(
 		// Scan for subdirectories containing SKILL.md
 		const entries = await fs.readdir(sourcePath, { withFileTypes: true })
 
-		for (const entry of entries) {
-			if (!entry.isDirectory()) continue
+		// One read for every candidate, and no separate probe: a directory with no
+		// SKILL.md comes back with nothing rather than being asked about twice.
+		const candidates = entries
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => path.join(sourcePath, entry.name, 'SKILL.md'))
+		const contents = await readTextFilesOrUndefined(fs, candidates)
 
-			const skillDir = path.join(sourcePath, entry.name)
-			const skillFile = path.join(skillDir, 'SKILL.md')
+		for (const [index, skillFile] of candidates.entries()) {
+			const content = contents[index]
+			if (content === undefined) continue
 
-			if (!(await fs.exists(skillFile))) continue
-
-			// Read and parse the skill file
-			const content = await fs.readFile(skillFile, 'utf-8')
 			const parseResult = parseSkillFrontmatter(content)
 
 			if (!parseResult.ok) {

package/src/plugins/skills/index.ts

@@ -13,7 +13,7 @@ export type {
 
 // Schema
 export { SkillId, skillIdSchema } from './schema.js'
-export type { LoadedSkill, SkillMetadata } from './schema.js'
+export type { LoadedSkill, LoadedSkillContent, SkillMetadata } from './schema.js'
 
 // Events & state slice (now in plugin.ts)
 export { skillEvents } from './plugin.js'

package/src/plugins/skills/plugin.ts

@@ -18,7 +18,7 @@ import { createTool } from '~/core/tools/definition.js'
 import { Err, Ok, type Result } from '~/lib/utils/result.js'
 import { discoverSkills, loadSkillContent } from './discovery.js'
 import { buildLoadedSkillsMessage, formatLoadedSkills } from './prompts.js'
-import { type LoadedSkill, SkillId, skillIdSchema, type SkillMetadata } from './schema.js'
+import { type LoadedSkill, type LoadedSkillContent, SkillId, skillIdSchema, type SkillMetadata } from './schema.js'
 
 /**
  * A preset-contributed skill. Skills are matched by name; file-discovered
@@ -96,7 +96,7 @@ export const skillEvents = createEvents({
 			agentId: agentIdSchema,
 			skillId: skillIdSchema,
 			skillName: z.string(),
-			content: z.string(),
+			content: z.string().optional(),
 		}),
 	},
 })
@@ -116,7 +116,6 @@ export const skillsPlugin = definePlugin('skills')
 					const loadedSkill: LoadedSkill = {
 						id: event.skillId,
 						name: event.skillName,
-						content: event.content,
 						loadedAt: event.timestamp,
 					}
 					const agentSkills = skills.get(event.agentId) ?? []
@@ -218,25 +217,22 @@ export const skillsPlugin = definePlugin('skills')
 				return Err(ValidationErrors.invalid(`Failed to load skill: ${contentResult.error.message}`))
 			}
 
-			// Emit skill_loaded event
-			await ctx.emitEvent(skillEvents.create('skill_loaded', {
-				agentId: input.agentId,
-				skillId: skillMeta.id,
-				skillName: skillMeta.name,
-				content: contentResult.value,
-			}))
-
-			// Emit preamble with the newly loaded skill
-			const skillContent = formatLoadedSkills([{
+			const loadedSkill: LoadedSkillContent = {
 				id: skillMeta.id,
 				name: skillMeta.name,
 				content: contentResult.value,
 				loadedAt: Date.now(),
-			}])
-			await ctx.emitEvent(agentEvents.create('preamble_added', {
+			}
+			const skillContent = formatLoadedSkills([loadedSkill])
+
+			await ctx.emitEvents([skillEvents.create('skill_loaded', {
+				agentId: input.agentId,
+				skillId: skillMeta.id,
+				skillName: skillMeta.name,
+			}), agentEvents.create('preamble_added', {
 				agentId: input.agentId,
 				messages: [{ role: 'system', content: skillContent }],
-			}))
+			})])
 
 			return Ok({
 				skillId: skillMeta.id,
@@ -286,7 +282,7 @@ export const skillsPlugin = definePlugin('skills')
 		// Load preload skills
 		const availableSkills = ctx.pluginContext.availableSkills
 		const skillByName = new Map(availableSkills.map((s) => [s.name, s]))
-		const newlyLoaded: LoadedSkill[] = []
+		const newlyLoaded: LoadedSkillContent[] = []
 
 		for (const skillName of preloadSkills) {
 			const skillMeta = skillByName.get(skillName)
@@ -308,14 +304,6 @@ export const skillsPlugin = definePlugin('skills')
 				continue
 			}
 
-			// Emit skill_loaded event
-			await ctx.emitEvent(skillEvents.create('skill_loaded', {
-				agentId: ctx.agentId,
-				skillId: skillMeta.id,
-				skillName: skillMeta.name,
-				content: contentResult.value,
-			}))
-
 			newlyLoaded.push({
 				id: skillMeta.id,
 				name: skillMeta.name,
@@ -328,10 +316,14 @@ export const skillsPlugin = definePlugin('skills')
 		if (newlyLoaded.length > 0) {
 			const skillsMessage = buildLoadedSkillsMessage(newlyLoaded)
 			if (skillsMessage) {
-				await ctx.emitEvent(agentEvents.create('preamble_added', {
+				await ctx.emitEvents([...newlyLoaded.map((skill) => skillEvents.create('skill_loaded', {
+					agentId: ctx.agentId,
+					skillId: skill.id,
+					skillName: skill.name,
+				})), agentEvents.create('preamble_added', {
 					agentId: ctx.agentId,
 					messages: [{ role: 'system', content: skillsMessage }],
-				}))
+				})])
 			}
 		}
 

package/src/plugins/skills/prompts.ts

@@ -2,7 +2,7 @@
  * Skills Prompt Sections - Build prompt sections for skill metadata and loaded skills.
  */
 
-import type { LoadedSkill, SkillMetadata } from './schema.js'
+import type { LoadedSkillContent, SkillMetadata } from './schema.js'
 
 // ============================================================================
 // Available Skills Section
@@ -46,7 +46,7 @@ export function buildSkillsSection(skills: SkillMetadata[]): string {
  * @param loadedSkills - Array of skills loaded into agent context
  * @returns Formatted string with all loaded skill content
  */
-export function formatLoadedSkills(loadedSkills: LoadedSkill[]): string {
+export function formatLoadedSkills(loadedSkills: LoadedSkillContent[]): string {
 	if (loadedSkills.length === 0) {
 		return ''
 	}
@@ -69,7 +69,7 @@ ${skill.content}
  * @param loadedSkills - Array of skills loaded into agent context
  * @returns System message content or null
  */
-export function buildLoadedSkillsMessage(loadedSkills: LoadedSkill[]): string | null {
+export function buildLoadedSkillsMessage(loadedSkills: LoadedSkillContent[]): string | null {
 	if (loadedSkills.length === 0) {
 		return null
 	}