@namzu/sdk 45.1.0 → 48.0.0

package/src/peers/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Cross-session peer messaging: the live-session registry, the
+ * `namzu-peer/1` transport, and the runtime-context rendering for a
+ * delivered message or notice (design "Sessions that talk", Part 1, §1.1-1.3,
+ * §1.7, and the SDK half of §1.4/§1.8, 2026-09-24).
+ *
+ * This module is the transport and storage layer only. Inbox policy —
+ * bounded queues, the mode-mismatch hold/approve flow, `/peers off`,
+ * subscriber bookkeeping and its 24h expiry, and drain-at-iteration-boundary
+ * injection — is host (CLI) territory and is not implemented here.
+ *
+ * @experimental
+ */
+
+export { parsePeerAddress, pipePeerAddress, PeerAddressError, udsPeerAddress } from './address.js'
+export type { PeerAddress } from './address.js'
+
+export {
+	hardenPeerRuntimeDir,
+	LONGEST_PEER_SOCKET_FILE_NAME_LENGTH,
+	PeerDirectoryError,
+	peerSocketFileName,
+	resolvePeerRuntimeDir,
+} from './dir.js'
+export type { HardenPeerDirectory, PeerRuntimeDir, ResolvePeerRuntimeDirOptions } from './dir.js'
+
+export { derivePeerRef, PEER_RECORD_VERSION, PeerRecordSchema } from './record.js'
+export type { PeerRecord } from './record.js'
+
+export {
+	isPeerRecordLive,
+	listLivePeers,
+	PeerRegistryError,
+	readPeerRecord,
+	readPeerRecords,
+	removePeerRecord,
+	writePeerRecord,
+} from './registry.js'
+export type { ListLivePeersOptions, PeerLivenessOptions } from './registry.js'
+
+export {
+	DEFAULT_PEER_READ_DEADLINE_MS,
+	DeliverRequestSchema,
+	DeliverResponseSchema,
+	DeliverStatusSchema,
+	MAX_PEER_CONNECTIONS,
+	MAX_PEER_MESSAGE_TEXT_BYTES,
+	MAX_PEER_REQUEST_BYTES,
+	NoticeRequestSchema,
+	NoticeResponseSchema,
+	PEER_PROTOCOL_VERSION,
+	PeerFromSchema,
+	PeerNoticeAboutSchema,
+	PeerNoticePayloadSchema,
+	PeerRefSchema,
+	PeerRequestSchema,
+	PeerSessionKindSchema,
+	PeerSessionStateSchema,
+	PingRequestSchema,
+	PingResponseSchema,
+	SubscribeIdleRequestSchema,
+	SubscribeIdleResponseSchema,
+} from './protocol.js'
+export type {
+	DeliverRequest,
+	DeliverResponse,
+	DeliverStatus,
+	NoticeRequest,
+	NoticeResponse,
+	PeerFrom,
+	PeerNoticeAbout,
+	PeerNoticePayload,
+	PeerRequest,
+	PeerResponse,
+	PeerSessionKind,
+	PeerSessionState,
+	PingRequest,
+	PingResponse,
+	SubscribeIdleRequest,
+	SubscribeIdleResponse,
+} from './protocol.js'
+
+export {
+	createPeerEndpoint,
+	MAX_OUTSTANDING_PEERS,
+	MAX_OUTSTANDING_PER_PEER,
+	OUTSTANDING_EXPIRY_MS,
+	PeerEndpointError,
+} from './endpoint.js'
+export type { CreatePeerEndpointOptions, PeerEndpoint } from './endpoint.js'
+
+export { PeerClient, PeerClientError, pingPeer } from './client.js'
+export type { PeerClientOptions, PeerClientResult } from './client.js'
+
+export { formatPeerMessage, formatPeerNotice } from './envelope.js'
+export type { PeerMessageEnvelopeInput } from './envelope.js'

package/src/peers/protocol.ts

@@ -0,0 +1,196 @@
+/**
+ * The `namzu-peer/1` wire protocol: newline-delimited JSON, one request and
+ * one response per connection, a closed set of four operations (design
+ * §1.1, §1.3).
+ *
+ * Two deliberate departures from the design note, both narrow and both
+ * documented where they matter most:
+ *
+ * 1. **`ping` carries no token.** Every other op requires and verifies the
+ *    recipient's token; `ping` is idempotent, has no side effect, and its
+ *    answer (`{ok, state}`) discloses nothing the OS-user directory
+ *    permission does not already gate (design §1.1: "the directory
+ *    permission is the real gate"). `PeerClient.ping(address)` — the shape
+ *    the spec's own client API names — takes no record and so has no token
+ *    to send.
+ * 2. **`notice`'s `delivery` kind carries an optional `outcome`.** The design
+ *    lists `notice`'s payload as `{kind, about, detail?}` with prose detail
+ *    ("approved" / "denied" / "expired") for a delivery outcome, but gives
+ *    `formatSystemEvent` a closed status set that a delivery notice must
+ *    report from (`queued` | `held` | `refused`). `outcome` supplies that
+ *    machine-readable status without parsing `detail`'s prose.
+ *
+ * @experimental
+ */
+
+import { z } from 'zod'
+
+export const PEER_PROTOCOL_VERSION = 'namzu-peer/1'
+
+/** One request line, or one response line, must not exceed this many bytes. */
+export const MAX_PEER_REQUEST_BYTES = 64 * 1024
+/** `deliver.text` must not exceed this many UTF-8 bytes. */
+export const MAX_PEER_MESSAGE_TEXT_BYTES = 32 * 1024
+/** A connection that has not completed one request/response by this deadline is dropped. */
+export const DEFAULT_PEER_READ_DEADLINE_MS = 2_000
+/** Concurrent connections a `createPeerEndpoint` server accepts before refusing new ones. */
+export const MAX_PEER_CONNECTIONS = 16
+
+export const PeerSessionKindSchema = z.enum(['tui', 'exec', 'resident', 'scheduled'])
+export type PeerSessionKind = z.infer<typeof PeerSessionKindSchema>
+
+export const PeerSessionStateSchema = z.enum(['busy', 'idle', 'awaiting-permission'])
+export type PeerSessionState = z.infer<typeof PeerSessionStateSchema>
+
+const REF_PATTERN = /^[0-9a-f]{6}$/
+
+/** First 6 hex characters of `sha256(sessionId)` — see `registry.ts` `derivePeerRef`. */
+export const PeerRefSchema = z.string().regex(REF_PATTERN, 'must be 6 lowercase hex characters')
+
+function byteLimitedString(maxBytes: number, message: string) {
+	return z
+		.string()
+		.min(1)
+		.refine((value) => Buffer.byteLength(value, 'utf8') <= maxBytes, { message })
+}
+
+/** The sender's asserted identity, checked by the recipient against its own registry (§1.3). */
+export const PeerFromSchema = z
+	.object({
+		sessionId: z.string().min(1),
+		ref: PeerRefSchema,
+		name: z.string(),
+		address: z.string().min(1),
+		mode: z.string().min(1),
+		kind: PeerSessionKindSchema,
+	})
+	.strict()
+export type PeerFrom = z.infer<typeof PeerFromSchema>
+
+// ─── ping ──────────────────────────────────────────────────────────────────
+
+export const PingRequestSchema = z
+	.object({
+		protocol: z.literal(PEER_PROTOCOL_VERSION),
+		op: z.literal('ping'),
+	})
+	.strict()
+export type PingRequest = z.infer<typeof PingRequestSchema>
+
+export const PingResponseSchema = z
+	.object({
+		ok: z.boolean(),
+		state: PeerSessionStateSchema,
+	})
+	.strict()
+export type PingResponse = z.infer<typeof PingResponseSchema>
+
+// ─── deliver ─────────────────────────────────────────────────────────────
+
+export const DeliverRequestSchema = z
+	.object({
+		protocol: z.literal(PEER_PROTOCOL_VERSION),
+		op: z.literal('deliver'),
+		token: z.string().min(1),
+		id: z.string().min(1),
+		from: PeerFromSchema,
+		text: byteLimitedString(
+			MAX_PEER_MESSAGE_TEXT_BYTES,
+			`must be at most ${MAX_PEER_MESSAGE_TEXT_BYTES} UTF-8 bytes`,
+		),
+		inReplyTo: z.string().min(1).optional(),
+		subscribeIdle: z.boolean().optional(),
+	})
+	.strict()
+export type DeliverRequest = z.infer<typeof DeliverRequestSchema>
+
+export const DeliverStatusSchema = z.enum(['queued', 'held', 'refused'])
+export type DeliverStatus = z.infer<typeof DeliverStatusSchema>
+
+export const DeliverResponseSchema = z
+	.object({
+		status: DeliverStatusSchema,
+		reason: z.string().optional(),
+	})
+	.strict()
+export type DeliverResponse = z.infer<typeof DeliverResponseSchema>
+
+// ─── subscribe_idle ────────────────────────────────────────────────────────
+
+export const SubscribeIdleRequestSchema = z
+	.object({
+		protocol: z.literal(PEER_PROTOCOL_VERSION),
+		op: z.literal('subscribe_idle'),
+		token: z.string().min(1),
+		id: z.string().min(1),
+		from: PeerFromSchema,
+	})
+	.strict()
+export type SubscribeIdleRequest = z.infer<typeof SubscribeIdleRequestSchema>
+
+export const SubscribeIdleResponseSchema = z
+	.object({
+		status: z.enum(['subscribed', 'refused']),
+	})
+	.strict()
+export type SubscribeIdleResponse = z.infer<typeof SubscribeIdleResponseSchema>
+
+// ─── notice ────────────────────────────────────────────────────────────────
+
+export const PeerNoticeAboutSchema = z
+	.object({
+		sessionId: z.string().min(1),
+		name: z.string(),
+		ref: PeerRefSchema,
+	})
+	.strict()
+export type PeerNoticeAbout = z.infer<typeof PeerNoticeAboutSchema>
+
+export const NoticeRequestSchema = z
+	.object({
+		protocol: z.literal(PEER_PROTOCOL_VERSION),
+		op: z.literal('notice'),
+		token: z.string().min(1),
+		/**
+		 * The sender's asserted identity, checked the same way `deliver` and
+		 * `subscribe_idle` check theirs (§1.3): the recipient's endpoint runs it
+		 * through `verifySender` before calling `onNotice`. A notice with no
+		 * `from` — the shape this protocol shipped with first — is not a
+		 * well-formed request at all, the same as a `deliver` with no `from`.
+		 */
+		from: PeerFromSchema,
+		kind: z.enum(['idle', 'exited', 'delivery']),
+		about: PeerNoticeAboutSchema,
+		/** Only meaningful, and only ever set, when `kind === 'delivery'`. */
+		outcome: DeliverStatusSchema.optional(),
+		detail: z.string().optional(),
+	})
+	.strict()
+export type NoticeRequest = z.infer<typeof NoticeRequestSchema>
+
+export const NoticeResponseSchema = z
+	.object({
+		ok: z.boolean(),
+	})
+	.strict()
+export type NoticeResponse = z.infer<typeof NoticeResponseSchema>
+
+/** The notice payload alone, with no envelope — what a host builds and what `formatPeerNotice` renders. */
+export const PeerNoticePayloadSchema = NoticeRequestSchema.omit({
+	protocol: true,
+	op: true,
+	token: true,
+})
+export type PeerNoticePayload = z.infer<typeof PeerNoticePayloadSchema>
+
+// ─── the closed op set ───────────────────────────────────────────────────
+
+export const PeerRequestSchema = z.discriminatedUnion('op', [
+	PingRequestSchema,
+	DeliverRequestSchema,
+	SubscribeIdleRequestSchema,
+	NoticeRequestSchema,
+])
+export type PeerRequest = z.infer<typeof PeerRequestSchema>
+
+export type PeerResponse = PingResponse | DeliverResponse | SubscribeIdleResponse | NoticeResponse

package/src/peers/record.ts

@@ -0,0 +1,56 @@
+/**
+ * The live-session registry record (design §1.2): one JSON file per
+ * participating session, written into a hardened runtime directory's
+ * `sessions/` subdirectory (`resolvePeerRuntimeDir`, `dir.ts`).
+ *
+ * Kept separate from `registry.ts` (which reads and writes these files) so
+ * `client.ts` can depend on the record SHAPE without depending on file I/O,
+ * and `registry.ts` can depend on `client.ts` (to ping a peer for liveness)
+ * without a cycle.
+ *
+ * @experimental
+ */
+
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import {
+	PEER_PROTOCOL_VERSION,
+	PeerRefSchema,
+	PeerSessionKindSchema,
+	PeerSessionStateSchema,
+} from './protocol.js'
+
+/** Bumped only if the on-disk record shape changes incompatibly. */
+export const PEER_RECORD_VERSION = 1
+
+export const PeerRecordSchema = z
+	.object({
+		v: z.literal(PEER_RECORD_VERSION),
+		sessionId: z.string().min(1),
+		/** First 6 hex characters of `sha256(sessionId)`; disambiguates a colliding display name. */
+		ref: PeerRefSchema,
+		pid: z.number().int().positive(),
+		startedAt: z.number().int().nonnegative(),
+		kind: PeerSessionKindSchema,
+		/** Absent until the operator or the host sets one; the display name then falls back (design §1.2). */
+		title: z.string().optional(),
+		cwd: z.string().min(1),
+		/** The host's own permission-mode vocabulary; the SDK does not constrain its spelling. */
+		permissionMode: z.string().min(1),
+		state: PeerSessionStateSchema,
+		acceptsMessages: z.boolean(),
+		address: z.string().min(1),
+		token: z.string().min(1),
+		protocol: z.literal(PEER_PROTOCOL_VERSION),
+		cliVersion: z.string(),
+	})
+	.strict()
+
+export type PeerRecord = z.infer<typeof PeerRecordSchema>
+
+const PEER_REF_HEX_LENGTH = 6
+
+/** `ref`: the first 6 hex characters of `sha256(sessionId)`, for a short, stable, collision-resistant tag. */
+export function derivePeerRef(sessionId: string): string {
+	return createHash('sha256').update(sessionId, 'utf8').digest('hex').slice(0, PEER_REF_HEX_LENGTH)
+}

package/src/peers/registry.ts

@@ -0,0 +1,241 @@
+/**
+ * The live-session registry: one JSON file per participating session under a
+ * hardened runtime directory's `sessions/` subdirectory (design §1.2).
+ *
+ * @experimental
+ */
+
+import { randomBytes } from 'node:crypto'
+import {
+	closeSync,
+	fsyncSync,
+	lstatSync,
+	openSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	unlinkSync,
+	writeSync,
+} from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { parsePeerAddress } from './address.js'
+import { pingPeer } from './client.js'
+import { type PeerRecord, PeerRecordSchema } from './record.js'
+
+const RECORD_FILE_MODE = 0o600
+
+export class PeerRegistryError extends Error {
+	override readonly name = 'PeerRegistryError'
+}
+
+function recordPath(sessionsDir: string, sessionId: string): string {
+	return join(sessionsDir, `${sessionId}.json`)
+}
+
+function temporaryPathBeside(path: string): string {
+	return join(
+		dirname(path),
+		`.${basename(path)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`,
+	)
+}
+
+/** Publish `record` at `<sessionsDir>/<sessionId>.json`: fsynced temporary, then rename, mode 0600. */
+export function writePeerRecord(sessionsDir: string, record: PeerRecord): void {
+	const validated = PeerRecordSchema.safeParse(record)
+	if (!validated.success) {
+		throw new PeerRegistryError(`Invalid peer record: ${validated.error.message}`)
+	}
+	const parsed = validated.data
+	const path = recordPath(sessionsDir, parsed.sessionId)
+	const temporary = temporaryPathBeside(path)
+	const fd = openSync(temporary, 'wx', RECORD_FILE_MODE)
+	try {
+		writeSync(fd, `${JSON.stringify(parsed)}\n`)
+		fsyncSync(fd)
+	} finally {
+		closeSync(fd)
+	}
+	try {
+		renameSync(temporary, path)
+	} catch (error) {
+		try {
+			unlinkSync(temporary)
+		} catch {
+			// The rename already failed; a leftover temporary file is not this
+			// call's failure to report.
+		}
+		throw error
+	}
+}
+
+function parseRecordText(text: string): PeerRecord | undefined {
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(text)
+	} catch {
+		return undefined
+	}
+	const result = PeerRecordSchema.safeParse(parsed)
+	return result.success ? result.data : undefined
+}
+
+/** One session's record, or `undefined` if it has none or its file does not parse. */
+export function readPeerRecord(sessionsDir: string, sessionId: string): PeerRecord | undefined {
+	let text: string
+	try {
+		text = readFileSync(recordPath(sessionsDir, sessionId), 'utf8')
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+		throw error
+	}
+	return parseRecordText(text)
+}
+
+/**
+ * Every registry record in `sessionsDir` that parses.
+ *
+ * A file that fails to parse (mid-write, truncated, from a newer namzu) is
+ * skipped rather than thrown on: one malformed record must not make every
+ * other live session invisible to `list_sessions`.
+ */
+export function readPeerRecords(sessionsDir: string): PeerRecord[] {
+	let entries: string[]
+	try {
+		entries = readdirSync(sessionsDir)
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+		throw error
+	}
+	const records: PeerRecord[] = []
+	for (const entry of entries) {
+		if (!entry.endsWith('.json')) continue
+		let text: string
+		try {
+			text = readFileSync(join(sessionsDir, entry), 'utf8')
+		} catch {
+			continue // Vanished between readdir and read; not this reader's concern.
+		}
+		const record = parseRecordText(text)
+		if (record) records.push(record)
+	}
+	return records
+}
+
+/** Remove a path only if it is owned by `uid`; `undefined` skips the check (tests, or a platform with no uid). */
+function removeIfOwned(path: string, uid: number | undefined): void {
+	let entry: ReturnType<typeof lstatSync>
+	try {
+		entry = lstatSync(path)
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+		throw error
+	}
+	if (uid !== undefined && entry.uid !== uid) return
+	try {
+		unlinkSync(path)
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+	}
+}
+
+/** Remove a session's registry record. Owner-checked: never unlinks a path this uid does not own. */
+export function removePeerRecord(
+	sessionsDir: string,
+	sessionId: string,
+	uid: number | undefined,
+): void {
+	removeIfOwned(recordPath(sessionsDir, sessionId), uid)
+}
+
+/** Remove a stale UDS socket file, only when it is a socket owned by `uid`. A `pipe:`/`a2a:` address is left alone. */
+function removeStaleSocketIfOwned(address: string, uid: number | undefined): void {
+	let parsed: ReturnType<typeof parsePeerAddress>
+	try {
+		parsed = parsePeerAddress(address)
+	} catch {
+		return
+	}
+	if (parsed.scheme !== 'uds') return
+	let entry: ReturnType<typeof lstatSync>
+	try {
+		entry = lstatSync(parsed.path)
+	} catch {
+		return
+	}
+	if (!entry.isSocket()) return
+	if (uid !== undefined && entry.uid !== uid) return
+	try {
+		unlinkSync(parsed.path)
+	} catch {
+		// Already gone, or another process just recreated it — either way there
+		// is nothing left for this cleanup pass to do.
+	}
+}
+
+function defaultIsPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch (error) {
+		// EPERM means the process exists but is owned by someone else, which
+		// cannot happen for a uid-owned registry entry under normal operation;
+		// treated as alive because this check cannot disprove it either way.
+		return (error as NodeJS.ErrnoException).code === 'EPERM'
+	}
+}
+
+export interface PeerLivenessOptions {
+	/** Default 500ms (design §1.2). */
+	readonly pingTimeoutMs?: number
+	/** Injectable for tests. Defaults to `process.kill(pid, 0)`. */
+	readonly isPidAlive?: (pid: number) => boolean
+	/** Injectable for tests. Defaults to an unauthenticated `ping` (`pingPeer` in `client.ts`). */
+	readonly ping?: (address: string, timeoutMs: number) => Promise<boolean>
+}
+
+/**
+ * A record is live iff its pid is alive AND its address answers a ping
+ * within the timeout (design §1.2). Shared by {@link listLivePeers} and by
+ * `createPeerEndpoint`'s default `verifySender` (`endpoint.ts`), so both
+ * apply exactly the same definition of "live".
+ */
+export async function isPeerRecordLive(
+	record: PeerRecord,
+	options: PeerLivenessOptions = {},
+): Promise<boolean> {
+	const isPidAlive = options.isPidAlive ?? defaultIsPidAlive
+	const ping = options.ping ?? pingPeer
+	const timeoutMs = options.pingTimeoutMs ?? 500
+	return isPidAlive(record.pid) && (await ping(record.address, timeoutMs))
+}
+
+export interface ListLivePeersOptions extends PeerLivenessOptions {
+	readonly sessionsDir: string
+	/** Owner-checks every removal; `undefined` skips the check (tests, or a platform with no uid). */
+	readonly uid: number | undefined
+}
+
+/**
+ * Every record in the registry that is live (see {@link isPeerRecordLive}).
+ *
+ * A record that is not live is DEAD: its registry file and, if it names a
+ * UDS socket, the socket file are removed — but only when owned by this
+ * uid, so one user's stale cleanup pass can never touch another's files
+ * even if it could somehow see them.
+ */
+export async function listLivePeers(options: ListLivePeersOptions): Promise<PeerRecord[]> {
+	const records = readPeerRecords(options.sessionsDir)
+	const live: PeerRecord[] = []
+	await Promise.all(
+		records.map(async (record) => {
+			const alive = await isPeerRecordLive(record, options)
+			if (alive) {
+				live.push(record)
+				return
+			}
+			removePeerRecord(options.sessionsDir, record.sessionId, options.uid)
+			removeStaleSocketIfOwned(record.address, options.uid)
+		}),
+	)
+	return live
+}

package/src/plugin/define.ts

@@ -0,0 +1,68 @@
+import type { PluginHookDefinition, PluginMCPServerConfig } from '../types/plugin/index.js'
+import { PluginManifestSchema, assertPluginHookEvent } from '../types/plugin/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+
+/** A host-authored plugin that needs no manifest file or dynamic import. */
+export interface DefinedPlugin {
+	readonly name: string
+	readonly version: string
+	readonly description: string
+	readonly tools: readonly ToolDefinition[]
+	readonly hooks: readonly PluginHookDefinition[]
+	readonly instructions?: string
+	readonly mcpServers: readonly PluginMCPServerConfig[]
+}
+
+export interface DefinePluginOptions {
+	readonly name: string
+	readonly version?: string
+	readonly description?: string
+	readonly tools?: readonly ToolDefinition[]
+	readonly hooks?: readonly PluginHookDefinition[]
+	readonly instructions?: string
+	readonly mcpServers?: readonly PluginMCPServerConfig[]
+}
+
+/** Validate and snapshot a plugin supplied directly by the host. */
+export function definePlugin(options: DefinePluginOptions): DefinedPlugin {
+	const version = options.version ?? '0.0.0'
+	const description = options.description ?? `In-code plugin ${options.name}`
+	PluginManifestSchema.parse({
+		name: options.name,
+		version,
+		description,
+		instructions: options.instructions,
+		mcpServers: options.mcpServers,
+	})
+	for (const hook of options.hooks ?? []) assertPluginHookEvent(hook.event)
+	const toolNames = new Set<string>()
+	for (const tool of options.tools ?? []) {
+		if (toolNames.has(tool.name))
+			throw new Error(`Plugin "${options.name}" declares tool "${tool.name}" twice.`)
+		toolNames.add(tool.name)
+	}
+	const serverNames = new Set<string>()
+	for (const server of options.mcpServers ?? []) {
+		if (serverNames.has(server.name)) {
+			throw new Error(`Plugin "${options.name}" declares MCP server "${server.name}" twice.`)
+		}
+		serverNames.add(server.name)
+	}
+	return Object.freeze({
+		name: options.name,
+		version,
+		description,
+		tools: Object.freeze([...(options.tools ?? [])]),
+		hooks: Object.freeze([...(options.hooks ?? [])]),
+		...(options.instructions !== undefined ? { instructions: options.instructions } : {}),
+		mcpServers: Object.freeze(
+			(options.mcpServers ?? []).map((server) =>
+				Object.freeze({
+					...server,
+					...(server.args ? { args: Object.freeze([...server.args]) } : {}),
+					...(server.env ? { env: Object.freeze({ ...server.env }) } : {}),
+				}),
+			),
+		),
+	})
+}

package/src/plugin/index.ts

@@ -1,4 +1,6 @@
 export { discoverPlugins, loadPluginManifest, discoverAllPluginDirs } from './loader.js'
+export { definePlugin } from './define.js'
+export type { DefinedPlugin, DefinePluginOptions } from './define.js'
 export type { PluginDiscoveryOptions, PluginEnablementCapabilities } from './loader.js'
 export { PluginLifecycleManager } from './lifecycle.js'
 export { PluginResolver } from './resolver.js'