@namzu/sdk 46.0.0 → 48.0.0

package/dist/peers/protocol.js

@@ -0,0 +1,151 @@
+/**
+ * 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 const PeerSessionStateSchema = z.enum(['busy', 'idle', 'awaiting-permission']);
+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, message) {
+    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();
+// ─── ping ──────────────────────────────────────────────────────────────────
+export const PingRequestSchema = z
+    .object({
+    protocol: z.literal(PEER_PROTOCOL_VERSION),
+    op: z.literal('ping'),
+})
+    .strict();
+export const PingResponseSchema = z
+    .object({
+    ok: z.boolean(),
+    state: PeerSessionStateSchema,
+})
+    .strict();
+// ─── 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 const DeliverStatusSchema = z.enum(['queued', 'held', 'refused']);
+export const DeliverResponseSchema = z
+    .object({
+    status: DeliverStatusSchema,
+    reason: z.string().optional(),
+})
+    .strict();
+// ─── 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 const SubscribeIdleResponseSchema = z
+    .object({
+    status: z.enum(['subscribed', 'refused']),
+})
+    .strict();
+// ─── notice ────────────────────────────────────────────────────────────────
+export const PeerNoticeAboutSchema = z
+    .object({
+    sessionId: z.string().min(1),
+    name: z.string(),
+    ref: PeerRefSchema,
+})
+    .strict();
+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 const NoticeResponseSchema = z
+    .object({
+    ok: z.boolean(),
+})
+    .strict();
+/** 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,
+});
+// ─── the closed op set ───────────────────────────────────────────────────
+export const PeerRequestSchema = z.discriminatedUnion('op', [
+    PingRequestSchema,
+    DeliverRequestSchema,
+    SubscribeIdleRequestSchema,
+    NoticeRequestSchema,
+]);
+//# sourceMappingURL=protocol.js.map

package/dist/peers/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/peers/protocol.ts"],"names":[],"mappings":"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"}

package/dist/peers/record.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { z } from 'zod';
+/** Bumped only if the on-disk record shape changes incompatibly. */
+export declare const PEER_RECORD_VERSION = 1;
+export declare const PeerRecordSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    sessionId: z.ZodString;
+    /** First 6 hex characters of `sha256(sessionId)`; disambiguates a colliding display name. */
+    ref: z.ZodString;
+    pid: z.ZodNumber;
+    startedAt: z.ZodNumber;
+    kind: z.ZodEnum<["tui", "exec", "resident", "scheduled"]>;
+    /** Absent until the operator or the host sets one; the display name then falls back (design §1.2). */
+    title: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodString;
+    /** The host's own permission-mode vocabulary; the SDK does not constrain its spelling. */
+    permissionMode: z.ZodString;
+    state: z.ZodEnum<["busy", "idle", "awaiting-permission"]>;
+    acceptsMessages: z.ZodBoolean;
+    address: z.ZodString;
+    token: z.ZodString;
+    protocol: z.ZodLiteral<"namzu-peer/1">;
+    cliVersion: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "resident" | "exec" | "scheduled" | "tui";
+    v: 1;
+    sessionId: string;
+    token: string;
+    address: string;
+    cwd: string;
+    protocol: "namzu-peer/1";
+    startedAt: number;
+    state: "busy" | "idle" | "awaiting-permission";
+    permissionMode: string;
+    ref: string;
+    pid: number;
+    acceptsMessages: boolean;
+    cliVersion: string;
+    title?: string | undefined;
+}, {
+    kind: "resident" | "exec" | "scheduled" | "tui";
+    v: 1;
+    sessionId: string;
+    token: string;
+    address: string;
+    cwd: string;
+    protocol: "namzu-peer/1";
+    startedAt: number;
+    state: "busy" | "idle" | "awaiting-permission";
+    permissionMode: string;
+    ref: string;
+    pid: number;
+    acceptsMessages: boolean;
+    cliVersion: string;
+    title?: string | undefined;
+}>;
+export type PeerRecord = z.infer<typeof PeerRecordSchema>;
+/** `ref`: the first 6 hex characters of `sha256(sessionId)`, for a short, stable, collision-resistant tag. */
+export declare function derivePeerRef(sessionId: string): string;
+//# sourceMappingURL=record.d.ts.map

package/dist/peers/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/peers/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAQvB,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,eAAO,MAAM,gBAAgB;;;IAI3B,6FAA6F;;;;;IAK7F,sGAAsG;;;IAGtG,0FAA0F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASlF,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAIzD,8GAA8G;AAC9G,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/dist/peers/record.js

@@ -0,0 +1,45 @@
+/**
+ * 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();
+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) {
+    return createHash('sha256').update(sessionId, 'utf8').digest('hex').slice(0, PEER_REF_HEX_LENGTH);
+}
+//# sourceMappingURL=record.js.map

package/dist/peers/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/peers/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,qBAAqB,EACrB,aAAa,EACb,qBAAqB,EACrB,sBAAsB,GACtB,MAAM,eAAe,CAAA;AAEtB,oEAAoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAEpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC/B,MAAM,CAAC;IACP,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,6FAA6F;IAC7F,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACzC,IAAI,EAAE,qBAAqB;IAC3B,sGAAsG;IACtG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACtB,0FAA0F;IAC1F,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,KAAK,EAAE,sBAAsB;IAC7B,eAAe,EAAE,CAAC,CAAC,OAAO,EAAE;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,qBAAqB,CAAC;IAC1C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC;KACD,MAAM,EAAE,CAAA;AAIV,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAE7B,8GAA8G;AAC9G,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC9C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAA;AAClG,CAAC"}

package/dist/peers/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The live-session registry: one JSON file per participating session under a
+ * hardened runtime directory's `sessions/` subdirectory (design §1.2).
+ *
+ * @experimental
+ */
+import { type PeerRecord } from './record.js';
+export declare class PeerRegistryError extends Error {
+    readonly name = "PeerRegistryError";
+}
+/** Publish `record` at `<sessionsDir>/<sessionId>.json`: fsynced temporary, then rename, mode 0600. */
+export declare function writePeerRecord(sessionsDir: string, record: PeerRecord): void;
+/** One session's record, or `undefined` if it has none or its file does not parse. */
+export declare function readPeerRecord(sessionsDir: string, sessionId: string): PeerRecord | undefined;
+/**
+ * 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 declare function readPeerRecords(sessionsDir: string): PeerRecord[];
+/** Remove a session's registry record. Owner-checked: never unlinks a path this uid does not own. */
+export declare function removePeerRecord(sessionsDir: string, sessionId: string, uid: number | undefined): void;
+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 declare function isPeerRecordLive(record: PeerRecord, options?: PeerLivenessOptions): Promise<boolean>;
+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 declare function listLivePeers(options: ListLivePeersOptions): Promise<PeerRecord[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/peers/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/peers/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiBH,OAAO,EAAE,KAAK,UAAU,EAAoB,MAAM,aAAa,CAAA;AAI/D,qBAAa,iBAAkB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,uBAAsB;CAC5C;AAaD,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CA0B7E;AAaD,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAS7F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,EAAE,CAqBjE;AAmBD,qGAAqG;AACrG,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GAAG,SAAS,GACrB,IAAI,CAEN;AAuCD,MAAM,WAAW,mBAAmB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACxE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAKlB;AAED,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,kGAAkG;IAClG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAexF"}

package/dist/peers/registry.js

@@ -0,0 +1,213 @@
+/**
+ * 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 { PeerRecordSchema } from './record.js';
+const RECORD_FILE_MODE = 0o600;
+export class PeerRegistryError extends Error {
+    name = 'PeerRegistryError';
+}
+function recordPath(sessionsDir, sessionId) {
+    return join(sessionsDir, `${sessionId}.json`);
+}
+function temporaryPathBeside(path) {
+    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, record) {
+    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) {
+    let parsed;
+    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, sessionId) {
+    let text;
+    try {
+        text = readFileSync(recordPath(sessionsDir, sessionId), 'utf8');
+    }
+    catch (error) {
+        if (error.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) {
+    let entries;
+    try {
+        entries = readdirSync(sessionsDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const records = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        let text;
+        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, uid) {
+    let entry;
+    try {
+        entry = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (uid !== undefined && entry.uid !== uid)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.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, sessionId, uid) {
+    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, uid) {
+    let parsed;
+    try {
+        parsed = parsePeerAddress(address);
+    }
+    catch {
+        return;
+    }
+    if (parsed.scheme !== 'uds')
+        return;
+    let entry;
+    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) {
+    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.code === 'EPERM';
+    }
+}
+/**
+ * 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, options = {}) {
+    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+    const ping = options.ping ?? pingPeer;
+    const timeoutMs = options.pingTimeoutMs ?? 500;
+    return isPidAlive(record.pid) && (await ping(record.address, timeoutMs));
+}
+/**
+ * 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) {
+    const records = readPeerRecords(options.sessionsDir);
+    const live = [];
+    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;
+}
+//# sourceMappingURL=registry.js.map

package/dist/peers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/peers/registry.ts"],"names":[],"mappings":"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"}

package/dist/plugin/define.d.ts

@@ -0,0 +1,24 @@
+import type { PluginHookDefinition, PluginMCPServerConfig } 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 declare function definePlugin(options: DefinePluginOptions): DefinedPlugin;
+//# sourceMappingURL=define.d.ts.map

package/dist/plugin/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/plugin/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAA;AAE3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAA;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAA;CACrD;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAA;CACtD;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAyCxE"}

package/dist/plugin/define.js

@@ -0,0 +1,42 @@
+import { PluginManifestSchema, assertPluginHookEvent } from '../types/plugin/index.js';
+/** Validate and snapshot a plugin supplied directly by the host. */
+export function definePlugin(options) {
+    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();
+    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();
+    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 }) } : {}),
+        }))),
+    });
+}
+//# sourceMappingURL=define.js.map

package/dist/plugin/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/plugin/define.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAA;AAwBtF,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,OAA4B;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAA;IAC1C,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,kBAAkB,OAAO,CAAC,IAAI,EAAE,CAAA;IAC3E,oBAAoB,CAAC,KAAK,CAAC;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;QACP,WAAW;QACX,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,UAAU,EAAE,OAAO,CAAC,UAAU;KAC9B,CAAC,CAAA;IACF,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE;QAAE,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzE,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,WAAW,OAAO,CAAC,IAAI,oBAAoB,IAAI,CAAC,IAAI,UAAU,CAAC,CAAA;QAChF,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzB,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACrC,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QAC/C,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,WAAW,OAAO,CAAC,IAAI,0BAA0B,MAAM,CAAC,IAAI,UAAU,CAAC,CAAA;QACxF,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IAC7B,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;QACP,WAAW;QACX,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QAChD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QAChD,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrF,UAAU,EAAE,MAAM,CAAC,MAAM,CACxB,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CACzC,MAAM,CAAC,MAAM,CAAC;YACb,GAAG,MAAM;YACT,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC,CACF,CACD;KACD,CAAC,CAAA;AACH,CAAC"}

package/dist/plugin/index.d.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';