@roj-ai/sdk 0.1.36 → 0.2.2

package/src/plugins/git-status/plugin.ts

@@ -1,110 +1,211 @@
 /**
  * Git Status Plugin
  *
- * Polls git state (commits ahead of the default branch, uncommitted files,
- * last commit metadata) inside the session's workspace directory every few
- * seconds and emits a `git_status_changed` notification when the snapshot
- * changes. The worker DO persists the last snapshot into its session table so
- * versions sidebar and publish bars can render without reaching into the
- * sandbox on every page view.
+ * Reports the git state of a session's workspace — commits ahead of the default
+ * branch, uncommitted files, last commit metadata — as a `git_status_changed`
+ * notification whenever the snapshot moves. The worker DO persists the last one
+ * into its session table so versions sidebars and publish bars render without
+ * reaching into the sandbox on every page view.
+ *
+ * `platform.git` answers the four questions directly, which is how a host with no
+ * process table takes part. Without the port the plugin shells out to `git`, as
+ * it always has.
+ *
+ * *When* it reads is a host question too, because who may write the workspace is.
+ * Where the scheduler delivers its own wakes the process outlives them, so roj is
+ * not the only writer — an editor and dev servers touch the same directory, and
+ * nothing but a clock sees those: the 2 s poll runs there exactly as before. A
+ * host evicted between wakes has no such writer, and a repeating wake would keep
+ * it awake replaying its event log every period. So there nothing is armed: the
+ * plugin refreshes at the turn boundary that follows a tool call, and answers
+ * `git-status.refresh` when a client pulls.
+ *
+ * Where `platform.fsRevision` exists, the answer already in hand is replayed while
+ * that counter stands still. It covers the whole host filesystem, so a write in a
+ * neighbouring session costs this one a recomputation it did not need — the only
+ * direction a cache over a working tree may err.
  */
 
-import z from 'zod/v4'
 import { definePlugin } from '~/core/plugins/index.js'
+import type { SessionId } from '~/core/sessions/schema.js'
 import { sessionIdSchema } from '~/core/sessions/schema.js'
+import type { Logger } from '~/lib/logger/logger.js'
+import { Ok } from '~/lib/utils/result.js'
+import type { FsRevision } from '~/platform/fs-revision.js'
+import type { GitClient } from '~/platform/git.js'
 import type { ProcessRunner } from '~/platform/process.js'
+import { isLiveScheduler } from '~/platform/scheduler.js'
+import z from 'zod/v4'
 
 const POLL_INTERVAL_MS = 2000
 const GIT_TIMEOUT_MS = 5000
 const DEFAULT_BRANCH_FALLBACK = 'main'
 
-interface GitStatusSnapshot {
-	committedAhead: number
-	uncommittedFiles: number
-	lastCommitAt: number | null
-	lastCommitMessage: string | null
+const gitStatusSnapshotSchema = z.object({
+	committedAhead: z.number(),
+	uncommittedFiles: z.number(),
+	lastCommitAt: z.number().nullable(),
+	lastCommitMessage: z.string().nullable(),
+})
+
+const gitStatusChangedSchema = z.object({
+	sessionId: sessionIdSchema,
+	...gitStatusSnapshotSchema.shape,
+	updatedAt: z.number(),
+})
+
+type GitStatusSnapshot = z.infer<typeof gitStatusSnapshotSchema>
+type GitStatusChanged = z.infer<typeof gitStatusChangedSchema>
+
+interface SessionGitStatus {
+	/** Whether this host has a clock of its own; false means nothing may be armed. */
+	polls: boolean
+	/** The 2 s interval, on polling hosts only. */
+	interval?: ReturnType<typeof setInterval>
+	/** Last snapshot handed to clients — what a new one is compared against. */
+	lastSnapshot?: GitStatusSnapshot
+	/** Last snapshot and the filesystem revision it was read at, replayed while that revision stands. */
+	gated?: { revision: number; snapshot: GitStatusSnapshot }
+	defaultBranch?: string
+	/** A tool wrote in this workspace since the last turn boundary. */
+	touched: boolean
 }
 
 interface GitStatusPluginContext {
-	intervals: Map<string, NodeJS.Timeout>
-	lastSnapshots: Map<string, GitStatusSnapshot>
-	defaultBranches: Map<string, string>
+	sessions: Map<SessionId, SessionGitStatus>
+}
+
+export interface GitStatusPluginConfig {
+	/** Compare against this ref instead of the detected local default branch, e.g. origin/main. */
+	baseBranch?: string
+}
+
+/**
+ * The slice of a context a read needs. Session hooks, agent hooks and the method
+ * handler all satisfy it, so all three share one code path.
+ */
+interface GitStatusCallContext {
+	sessionId: SessionId
+	sessionState: { workspaceDir?: string }
+	platform: { git?: GitClient; process: ProcessRunner; fsRevision?: FsRevision }
+	logger: Logger
+	notify: (type: 'git_status_changed', payload: GitStatusChanged) => void
+	pluginContext: GitStatusPluginContext
+	pluginConfig?: GitStatusPluginConfig
 }
 
 export const gitStatusPlugin = definePlugin('git-status')
-	.notification('git_status_changed', {
-		schema: z.object({
-			sessionId: sessionIdSchema,
-			committedAhead: z.number(),
-			uncommittedFiles: z.number(),
-			lastCommitAt: z.number().nullable(),
-			lastCommitMessage: z.string().nullable(),
-			updatedAt: z.number(),
-		}),
+	.order(150)
+	.pluginConfig<GitStatusPluginConfig>()
+	.notification('git_status_changed', { schema: gitStatusChangedSchema })
+	.context(async (): Promise<GitStatusPluginContext> => ({ sessions: new Map() }))
+	.method('refresh', {
+		input: z.object({}),
+		output: z.object({ snapshot: gitStatusSnapshotSchema.nullable() }),
+		// The pull half of the contract: a client that just opened the session, or a
+		// host with no clock, asks instead of waiting for a poll to notice.
+		handler: async (ctx) => Ok({ snapshot: await refresh(ctx) }),
 	})
-	.context(async (): Promise<GitStatusPluginContext> => ({
-		intervals: new Map(),
-		lastSnapshots: new Map(),
-		defaultBranches: new Map(),
-	}))
 	.sessionHook('onSessionReady', async (ctx) => {
-		const workdir = ctx.sessionState.workspaceDir
-		if (!workdir) return
+		if (!ctx.sessionState.workspaceDir) return
+
+		const polls = isLiveScheduler(ctx.platform.scheduler)
+		const entry: SessionGitStatus = { polls, touched: false }
+		ctx.pluginContext.sessions.set(ctx.sessionId, entry)
+		if (!polls) return
 
-		const sessionId = ctx.sessionId
-		const pluginCtx = ctx.pluginContext
+		void refresh(ctx)
+		entry.interval = setInterval(() => void refresh(ctx), POLL_INTERVAL_MS)
+	})
+	.hook('afterToolCall', async (ctx) => {
+		// Only a mark: the read itself waits for the turn to end, and is skipped if no tool ran.
+		const entry = ctx.pluginContext.sessions.get(ctx.sessionId)
+		if (entry) entry.touched = true
+		return null
+	})
+	.hook('onComplete', async (ctx) => {
+		const entry = ctx.pluginContext.sessions.get(ctx.sessionId)
+		// A polling host already has this covered; elsewhere the turn boundary is the
+		// one moment the workspace demonstrably changed and nothing is armed.
+		if (!entry || entry.polls || !entry.touched) return null
+		entry.touched = false
+		await refresh(ctx)
+		return null
+	})
+	.sessionHook('onSessionClose', async (ctx) => {
+		const entry = ctx.pluginContext.sessions.get(ctx.sessionId)
+		if (entry?.interval) clearInterval(entry.interval)
+		ctx.pluginContext.sessions.delete(ctx.sessionId)
+	})
+	.build()
+
+/** Read the workspace's git state, notifying if it moved. Never rejects. */
+async function refresh(ctx: GitStatusCallContext): Promise<GitStatusSnapshot | null> {
+	const sessionId = ctx.sessionId
+	const entry = ctx.pluginContext.sessions.get(sessionId)
+	const workdir = ctx.sessionState.workspaceDir
+	if (!entry || !workdir) return null
+
+	try {
+		// Read the revision before the git calls, never after: a write landing while
+		// they run belongs to the next answer, and stamping the revision it produced
+		// would bury it.
+		const revision = await currentRevision(ctx)
+		const gated = entry.gated
+		if (revision !== undefined && gated?.revision === revision) return gated.snapshot
+
+		const git = ctx.platform.git
 		const processRunner = ctx.platform.process
 
-		const tick = async () => {
-			let baseBranch = pluginCtx.defaultBranches.get(sessionId)
-			if (!baseBranch) {
-				baseBranch = await detectDefaultBranch(processRunner, workdir) ?? DEFAULT_BRANCH_FALLBACK
-				pluginCtx.defaultBranches.set(sessionId, baseBranch)
-			}
-
-			const snapshot = await computeGitStatus(processRunner, workdir, baseBranch)
-			if (!snapshot) {
-				ctx.logger.warn('git-status: snapshot failed', { sessionId, workdir, baseBranch })
-				return
-			}
-
-			const last = pluginCtx.lastSnapshots.get(sessionId)
-			if (last && snapshotsEqual(last, snapshot)) return
-
-			pluginCtx.lastSnapshots.set(sessionId, snapshot)
-			ctx.notify('git_status_changed', {
-				sessionId,
-				committedAhead: snapshot.committedAhead,
-				uncommittedFiles: snapshot.uncommittedFiles,
-				lastCommitAt: snapshot.lastCommitAt,
-				lastCommitMessage: snapshot.lastCommitMessage,
-				updatedAt: Date.now(),
-			})
+		let baseBranch = ctx.pluginConfig?.baseBranch ?? entry.defaultBranch
+		if (!baseBranch) {
+			const detected = git
+				? await detectDefaultBranchOverPort(git, workdir)
+				: await detectDefaultBranch(processRunner, workdir)
+			baseBranch = detected ?? DEFAULT_BRANCH_FALLBACK
+			entry.defaultBranch = baseBranch
 		}
 
-		const runTick = () => {
-			tick().catch((err) => {
-				ctx.logger.warn('git-status tick failed', { sessionId, err: err instanceof Error ? err.message : String(err) })
-			})
+		const snapshot = git
+			? await computeGitStatusOverPort(git, workdir, baseBranch)
+			: await computeGitStatus(processRunner, workdir, baseBranch)
+		if (!snapshot) {
+			ctx.logger.warn('git-status: snapshot failed', { sessionId, workdir, baseBranch })
+			return null
 		}
 
-		runTick()
-		const interval = setInterval(runTick, POLL_INTERVAL_MS)
+		// The runtime may have been unloaded while the reads ran — onSessionClose drops
+		// the entry — and a notification then lands on nobody.
+		if (ctx.pluginContext.sessions.get(sessionId) !== entry) return null
 
-		pluginCtx.intervals.set(sessionId, interval)
-	})
-	.sessionHook('onSessionClose', async (ctx) => {
-		const sessionId = ctx.sessionId
-		const pluginCtx = ctx.pluginContext
-		const interval = pluginCtx.intervals.get(sessionId)
-		if (interval) {
-			clearInterval(interval)
-			pluginCtx.intervals.delete(sessionId)
+		// Only a completed read is worth gating on; a failure is not the filesystem's doing.
+		if (revision !== undefined) entry.gated = { revision, snapshot }
+
+		const last = entry.lastSnapshot
+		entry.lastSnapshot = snapshot
+		if (!last || !snapshotsEqual(last, snapshot)) {
+			ctx.notify('git_status_changed', { sessionId, ...snapshot, updatedAt: Date.now() })
 		}
-		pluginCtx.lastSnapshots.delete(sessionId)
-		pluginCtx.defaultBranches.delete(sessionId)
-	})
-	.build()
+		return snapshot
+	} catch (err) {
+		ctx.logger.warn('git-status refresh failed', { sessionId, err: err instanceof Error ? err.message : String(err) })
+		return null
+	}
+}
+
+/**
+ * The host's filesystem revision, or `undefined` when there is none to read.
+ *
+ * Defensive beyond the port's contract on purpose: this is an optimisation, and a
+ * host that answers badly must lose the optimisation, not the feature.
+ */
+async function currentRevision(ctx: GitStatusCallContext): Promise<number | undefined> {
+	try {
+		return await ctx.platform.fsRevision?.current()
+	} catch {
+		return undefined
+	}
+}
 
 function snapshotsEqual(a: GitStatusSnapshot, b: GitStatusSnapshot): boolean {
 	return a.committedAhead === b.committedAhead
@@ -113,6 +214,35 @@ function snapshotsEqual(a: GitStatusSnapshot, b: GitStatusSnapshot): boolean {
 		&& a.lastCommitMessage === b.lastCommitMessage
 }
 
+async function computeGitStatusOverPort(git: GitClient, workdir: string, baseBranch: string): Promise<GitStatusSnapshot | null> {
+	try {
+		const [committedAhead, commits, status] = await Promise.all([
+			git.countAhead({ dir: workdir, base: baseBranch }),
+			git.log({ dir: workdir, depth: 1 }),
+			git.status({ dir: workdir }),
+		])
+
+		const head = commits[0]
+		return {
+			committedAhead,
+			uncommittedFiles: status.length,
+			lastCommitAt: head?.committedAt ?? null,
+			// The shell path reads `%s`, the subject — so take the same first line here.
+			lastCommitMessage: head ? subjectOf(head.message) : null,
+		}
+	} catch {
+		return null
+	}
+}
+
+async function detectDefaultBranchOverPort(git: GitClient, workdir: string): Promise<string | null> {
+	try {
+		return await git.defaultBranch({ dir: workdir }) ?? null
+	} catch {
+		return null
+	}
+}
+
 async function computeGitStatus(process: ProcessRunner, workdir: string, baseBranch: string): Promise<GitStatusSnapshot | null> {
 	const countOutput = await runGit(process, workdir, ['rev-list', '--count', `${baseBranch}..HEAD`])
 	if (countOutput === null) return null
@@ -157,6 +287,10 @@ async function runGit(process: ProcessRunner, workdir: string, args: string[]):
 	}
 }
 
+function subjectOf(message: string): string | null {
+	return message.split('\n', 1)[0]?.trim() || null
+}
+
 function countNonEmptyLines(output: string): number {
 	let count = 0
 	for (const line of output.split('\n')) {

package/src/plugins/llm-debug/plugin.ts

@@ -82,6 +82,7 @@ function formatCurl(httpRequest: { url: string; method: string; headers: Record<
 // ============================================================================
 
 export const llmDebugPlugin = definePlugin('llm')
+	.order(90)
 	.method('getCalls', {
 		input: z4.object({
 			limit: z4.number().int().optional(),

package/src/plugins/logs/plugin.ts

@@ -4,11 +4,20 @@ import { definePlugin } from '~/core/plugins/plugin-builder.js'
 import { Ok } from '~/lib/utils/result.js'
 
 export const logsPlugin = definePlugin('logs')
+	.order(120)
 	.method('tail', {
 		input: z.object({ since: z.number().int().min(0).optional() }),
 		output: z.object({ lines: z.array(z.string()), offset: z.number() }),
 		handler: async (ctx, input) => {
 			const since = input.since ?? 0
+
+			// Where the host keeps the log in rows, the cursor counts entries instead of
+			// bytes. Both are opaque to the caller — it only ever hands `offset` back.
+			const store = ctx.platform.sessionLog
+			if (store !== undefined) {
+				return Ok(await store.read(String(ctx.sessionId), since))
+			}
+
 			const logPath = resolve(ctx.environment.sessionDir, 'session.log')
 
 			let fileSize: number

package/src/plugins/mailbox/plugin.ts

@@ -9,7 +9,7 @@
 import z from "zod/v4";
 import { getAgentRole } from "~/core/agents/agent-roles.js";
 import { type AgentId, agentIdSchema } from "~/core/agents/schema.js";
-import { ValidationErrors } from "~/core/errors.js";
+import { SessionErrors, ValidationErrors } from "~/core/errors.js";
 import { definePlugin } from "~/core/plugins/plugin-builder.js";
 import { createTool } from "~/core/tools/definition.js";
 import type { ToolError } from "~/core/tools/index.js";
@@ -24,11 +24,10 @@ import {
 } from "./prompts.js";
 import {
 	getAgentUnconsumedMailbox,
-	getNextMessageSeq,
 	type MailboxPluginState,
 } from "./query.js";
 import { generateMessageId, type MessageId } from "./schema.js";
-import type { MailboxMessage } from "./schema.js";
+import type { MailboxMessage, MailboxMessageSender } from "./schema.js";
 import { mailboxEvents } from "./state.js";
 
 /**
@@ -45,6 +44,7 @@ export interface MailboxAgentConfig {
 }
 
 export const mailboxPlugin = definePlugin("mailbox")
+	.order(30)
 	.pluginConfig<MailboxPresetConfig>()
 	.agentConfig<MailboxAgentConfig>()
 	.events([mailboxEvents])
@@ -52,6 +52,7 @@ export const mailboxPlugin = definePlugin("mailbox")
 		key: "mailbox",
 		initial: (): MailboxPluginState => ({
 			agentMailboxes: new Map(),
+			messageSequence: 0,
 		}),
 		reduce: (state, event) => {
 			switch (event.type) {
@@ -59,9 +60,16 @@ export const mailboxPlugin = definePlugin("mailbox")
 					const agentMailbox = state.agentMailboxes.get(event.toAgentId) ?? [];
 					const newMailboxes = new Map(state.agentMailboxes);
 					newMailboxes.set(event.toAgentId, [...agentMailbox, event.message]);
+					const parsedSequence = /^m(\d+)$/.exec(event.message.id);
+					const messageSequence = Math.max(
+						state.messageSequence ?? 0,
+						event.sequence ?? 0,
+						parsedSequence ? Number(parsedSequence[1]) : (state.messageSequence ?? 0) + 1,
+					);
 					return {
 						...state,
 						agentMailboxes: newMailboxes,
+						messageSequence,
 					};
 				}
 
@@ -70,12 +78,9 @@ export const mailboxPlugin = definePlugin("mailbox")
 					if (!mailbox) return state;
 					const consumedSet = new Set(event.messageIds);
 					const newMailboxes = new Map(state.agentMailboxes);
-					newMailboxes.set(
-						event.agentId,
-						mailbox.map((m) =>
-							consumedSet.has(m.id) ? { ...m, consumed: true } : m,
-						),
-					);
+					const remaining = mailbox.filter((message) => !consumedSet.has(message.id));
+					if (remaining.length === 0) newMailboxes.delete(event.agentId);
+					else newMailboxes.set(event.agentId, remaining);
 					return { ...state, agentMailboxes: newMailboxes };
 				}
 
@@ -95,74 +100,51 @@ export const mailboxPlugin = definePlugin("mailbox")
 		output: z.object({ messageId: z.string() }),
 		handler: async (ctx, input) => {
 			const { toAgentId, content } = input;
-
-			if (input.fromSupervisor) {
-				// System-emitted supervision status — bypasses communication validation.
-				const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
-				await ctx.emitEvent(
-					mailboxEvents.create("mailbox_message", {
-						toAgentId,
-						message: {
-							id: messageId,
-							from: "supervisor",
-							content,
-							timestamp: Date.now(),
-							consumed: false,
-						},
-					}),
-				);
-				ctx.scheduleAgent(toAgentId);
-				return Ok({ messageId });
+			if (ctx.getSessionState().status === "closed") {
+				return Err(SessionErrors.closed(String(ctx.sessionId)));
 			}
 
-			if (input.debug) {
-				// Debug messages bypass communication validation
-				const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
-				await ctx.emitEvent(
-					mailboxEvents.create("mailbox_message", {
-						toAgentId,
-						message: {
-							id: messageId,
-							from: "debug",
-							content,
-							timestamp: Date.now(),
-							consumed: false,
-						},
-					}),
-				);
-				ctx.scheduleAgent(toAgentId);
-				return Ok({ messageId });
-			}
+			let from: MailboxMessageSender;
+			if (input.fromSupervisor) from = "supervisor";
+			else if (input.debug) from = "debug";
+			else {
+				const fromAgentId = input.fromAgentId;
+				if (!fromAgentId) {
+					return Err(
+						ValidationErrors.invalid(
+							"fromAgentId is required for non-debug messages",
+						),
+					);
+				}
 
-			const fromAgentId = input.fromAgentId;
-			if (!fromAgentId) {
-				return Err(
-					ValidationErrors.invalid(
-						"fromAgentId is required for non-debug messages",
-					),
-				);
+				if (!canCommunicateWith(ctx.getSessionState(), fromAgentId, toAgentId)) {
+					const allowed = getCommunicableAgents(ctx.getSessionState(), fromAgentId);
+					const allowedStr = allowed.length > 0 ? allowed.join(", ") : "none";
+					return Err(
+						ValidationErrors.invalid(
+							`Cannot send message to agent ${toAgentId}. You can only communicate with your parent or children. Allowed agents: ${allowedStr}`,
+						),
+					);
+				}
+				from = fromAgentId;
 			}
 
-			// Validate that the target agent is allowed
-			if (!canCommunicateWith(ctx.sessionState, fromAgentId, toAgentId)) {
-				const allowed = getCommunicableAgents(ctx.sessionState, fromAgentId);
-				const allowedStr = allowed.length > 0 ? allowed.join(", ") : "none";
-				return Err(
-					ValidationErrors.invalid(
-						`Cannot send message to agent ${toAgentId}. You can only communicate with your parent or children. Allowed agents: ${allowedStr}`,
-					),
-				);
+			let sequence: number;
+			try {
+				sequence = ctx.reserveMailboxMessageSequence();
+			} catch {
+				return Err(SessionErrors.closed(String(ctx.sessionId)));
 			}
-
-			const messageId = generateMessageId(getNextMessageSeq(ctx.pluginState));
+			const messageId = generateMessageId(sequence);
 			const now = Date.now();
 
 			await ctx.emitEvent(
 				mailboxEvents.create("mailbox_message", {
 					toAgentId,
+					sequence,
 					message: {
 						id: messageId,
-						from: fromAgentId,
+						from,
 						content,
 						timestamp: now,
 						consumed: false,

package/src/plugins/mailbox/query.ts

@@ -15,9 +15,11 @@ import type { MailboxMessage } from './schema.js'
  */
 export interface MailboxPluginState {
 	agentMailboxes: Map<AgentId, MailboxMessage[]>
+	/** Highest message sequence observed, including consumed messages. */
+	messageSequence?: number
 }
 
-const defaultState: MailboxPluginState = { agentMailboxes: new Map() }
+const defaultState: MailboxPluginState = { agentMailboxes: new Map(), messageSequence: 0 }
 
 /**
  * Extract MailboxPluginState from SessionState.
@@ -27,7 +29,10 @@ export function selectMailboxState(sessionState: SessionState): MailboxPluginSta
 }
 
 /**
- * Get all mailbox messages for a specific agent.
+ * Get pending mailbox messages for a specific agent.
+ *
+ * Consumed messages are removed from live state and remain available only in
+ * the event log.
  */
 export function getAgentMailbox(pluginState: MailboxPluginState, agentId: AgentId): MailboxMessage[] {
 	return pluginState.agentMailboxes.get(agentId) ?? []
@@ -37,17 +42,20 @@ export function getAgentMailbox(pluginState: MailboxPluginState, agentId: AgentI
  * Get unconsumed mailbox messages for a specific agent.
  */
 export function getAgentUnconsumedMailbox(pluginState: MailboxPluginState, agentId: AgentId): MailboxMessage[] {
-	return getAgentMailbox(pluginState, agentId).filter((m) => !m.consumed)
+	return getAgentMailbox(pluginState, agentId)
 }
 
 /**
  * Get the next message sequence number.
- * Derived from total message count across all mailboxes (replay-safe).
+ * Uses the persistent high-water mark so pruning cannot reuse IDs.
  */
 export function getNextMessageSeq(pluginState: MailboxPluginState): number {
-	let total = 0
+	let highest = pluginState.messageSequence ?? 0
 	for (const messages of pluginState.agentMailboxes.values()) {
-		total += messages.length
+		for (const message of messages) {
+			const match = /^m(\d+)$/.exec(message.id)
+			if (match) highest = Math.max(highest, Number(match[1]))
+		}
 	}
-	return total + 1
+	return highest + 1
 }

package/src/plugins/mailbox/state.ts

@@ -19,6 +19,7 @@ export const mailboxEvents = createEventsFactory({
 	events: {
 		mailbox_message: z4.object({
 			toAgentId: agentIdSchema,
+			sequence: z4.number().int().positive().optional(),
 			message: z4.object({
 				id: messageIdSchema,
 				from: z4.union([

package/src/plugins/resources/filename.ts

@@ -0,0 +1,19 @@
+import { posix, win32 } from 'node:path'
+import z from 'zod/v4'
+
+export function isResourceBasename(filename: string): boolean {
+	return filename.length > 0
+		&& !filename.includes('\0')
+		&& !filename.includes('/')
+		&& !filename.includes('\\')
+		&& filename !== '.'
+		&& filename !== '..'
+		&& !posix.isAbsolute(filename)
+		&& !win32.isAbsolute(filename)
+		&& posix.basename(filename) === filename
+		&& win32.basename(filename) === filename
+}
+
+export const ResourceBasenameSchema = z.string().refine(isResourceBasename, {
+	message: 'Resource filename must be a basename',
+})