@excitedjs/dreamux-utils 0.1.1-alpha.g0ddd418597ca

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 excitedjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @excitedjs/dreamux-utils
+
+Pure shared utilities for the Dreamux host and its provider packages
+(issue [#209](https://github.com/excitedjs/dreamux/issues/209)). These are the
+byte-identical helpers that were previously vendored separately into the codex,
+claude-code, and feishu-channel packages and the host core; consolidating them
+removes the duplication while keeping the provider packages free of any
+dependency on `@excitedjs/dreamux` core.
+
+This package depends on `@excitedjs/dreamux-types` only — never on
+`@excitedjs/dreamux`.
+
+## Exports
+
+- **config-validate** — neutral JSON-shape validation primitives that produce
+  `dreamux config error in <file>: ...` messages (`isPlainObject`,
+  `rejectUnknownKeys`, `requireNonEmptyString`, `requireStringArray`, …).
+- **os** — platform/filesystem primitives (`isProcessAlive`, `killProcessGroup`,
+  `ensureOwnerOnlyDir`, `removeEmptyLogFile`, `pathExists`). These are generic OS
+  helpers, not Dreamux layout/path contracts.
+- **completion-body** — bounded teammate-completion resolution: inline a short
+  result, spill an over-budget result to an owner-only file under a
+  host-supplied spill directory (`resolveCompletionBody`,
+  `completionInlineBudget`, `teamMateCompletionOutputPath`,
+  `COMPLETION_INLINE_BUDGET_DEFAULT`, `COMPLETION_INLINE_BUDGET_MAX`).
+- **turn-render** — inbound-turn render helpers that wrap a neutral
+  `InboundTurnInput` into the native `<channel source="…" …>` envelope
+  (`renderChannelInput`, `renderChannelBlock`,
+  `DEFAULT_MESSAGE_ID_DEDUPE_WINDOW`).

package/dist/completion-body.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Neutral completion-body resolution shared by every runtime and the host.
+ *
+ * A teammate completion is delivered back to the dispatcher as turn text. When
+ * the result is short it is inlined verbatim; when it overflows the inline
+ * budget the full result is spilled to an owner-only 0600 file under the
+ * host-supplied spill directory and only the path is inlined, so a large result
+ * never floods the dispatcher's context window.
+ *
+ * The spill directory is supplied by the caller (the host through its path
+ * context, or a runtime through the create context), so this module owns no
+ * Dreamux layout contract — only the safe filename shape inside that directory.
+ */
+import type { CompletionEnvelope } from '@excitedjs/dreamux-types';
+/**
+ * Inline character budget, mirroring claude-code's native task-output budget
+ * (`getMaxTaskOutputLength`): default 32000 chars, `TASK_MAX_OUTPUT_LENGTH`
+ * override, clamped to 160000. Counted in characters, not bytes.
+ */
+export declare const COMPLETION_INLINE_BUDGET_DEFAULT = 32000;
+export declare const COMPLETION_INLINE_BUDGET_MAX = 160000;
+export type ResolvedCompletionBody = {
+    kind: 'inline';
+    text: string;
+} | {
+    kind: 'spilled';
+    path: string;
+};
+/**
+ * Spill file for a teammate completion result that overflows the inline budget.
+ * Both runtimes write the full result here and inline only this path into the
+ * dispatcher turn, so a large result never floods the dispatcher's context.
+ * `spillDir` is the owning dispatcher's completion spill dir, supplied by the
+ * caller so a teammate runtime spills under its operator dispatcher, not its
+ * composite runtime id. `source` and `id` are sanitized for filename safety; the
+ * id is unique per completion (teammate name + turn id).
+ */
+export declare function teamMateCompletionOutputPath(spillDir: string, source: string, id: string): string;
+/**
+ * Resolve the effective inline budget from the environment, in the spirit of
+ * native `validateBoundedIntEnvVar`: unset/blank or non-positive falls back to
+ * the default; values above the upper bound are clamped (not rejected). Stricter
+ * than native's lenient `parseInt`, a value that is not a plain decimal integer
+ * (e.g. `32k` or `123abc`) falls back to the default rather than being partially
+ * parsed.
+ */
+export declare function completionInlineBudget(env?: NodeJS.ProcessEnv): number;
+/**
+ * Decide whether a completion result is inlined or spilled. Spilling writes the
+ * FULL result to a 0600 file (async fs only — no sync IO, repo rule #85) under
+ * the caller-supplied `spillDir` and returns the path; the caller inlines only
+ * that path. `spillDir` is supplied by the caller, so this module stays
+ * runtime-neutral and never names a dispatcher id.
+ */
+export declare function resolveCompletionBody(completion: CompletionEnvelope, spillDir: string): Promise<ResolvedCompletionBody>;
+//# sourceMappingURL=completion-body.d.ts.map

package/dist/completion-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-body.d.ts","sourceRoot":"","sources":["../src/completion-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AACvD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAGpD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAOtC;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,GACT,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAmC,GAC9C,MAAM,CAUR;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,sBAAsB,CAAC,CAkBjC"}

package/dist/completion-body.js

@@ -0,0 +1,82 @@
+/**
+ * Neutral completion-body resolution shared by every runtime and the host.
+ *
+ * A teammate completion is delivered back to the dispatcher as turn text. When
+ * the result is short it is inlined verbatim; when it overflows the inline
+ * budget the full result is spilled to an owner-only 0600 file under the
+ * host-supplied spill directory and only the path is inlined, so a large result
+ * never floods the dispatcher's context window.
+ *
+ * The spill directory is supplied by the caller (the host through its path
+ * context, or a runtime through the create context), so this module owns no
+ * Dreamux layout contract — only the safe filename shape inside that directory.
+ */
+import { chmod, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureOwnerOnlyDir } from './os.js';
+/**
+ * Inline character budget, mirroring claude-code's native task-output budget
+ * (`getMaxTaskOutputLength`): default 32000 chars, `TASK_MAX_OUTPUT_LENGTH`
+ * override, clamped to 160000. Counted in characters, not bytes.
+ */
+export const COMPLETION_INLINE_BUDGET_DEFAULT = 32_000;
+export const COMPLETION_INLINE_BUDGET_MAX = 160_000;
+const COMPLETION_INLINE_BUDGET_ENV = 'TASK_MAX_OUTPUT_LENGTH';
+/** Sanitize a name into a safe single path segment. */
+function safeSegment(name) {
+    return name.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+/**
+ * Spill file for a teammate completion result that overflows the inline budget.
+ * Both runtimes write the full result here and inline only this path into the
+ * dispatcher turn, so a large result never floods the dispatcher's context.
+ * `spillDir` is the owning dispatcher's completion spill dir, supplied by the
+ * caller so a teammate runtime spills under its operator dispatcher, not its
+ * composite runtime id. `source` and `id` are sanitized for filename safety; the
+ * id is unique per completion (teammate name + turn id).
+ */
+export function teamMateCompletionOutputPath(spillDir, source, id) {
+    return join(spillDir, `teammate-${safeSegment(source)}-${safeSegment(id)}.output`);
+}
+/**
+ * Resolve the effective inline budget from the environment, in the spirit of
+ * native `validateBoundedIntEnvVar`: unset/blank or non-positive falls back to
+ * the default; values above the upper bound are clamped (not rejected). Stricter
+ * than native's lenient `parseInt`, a value that is not a plain decimal integer
+ * (e.g. `32k` or `123abc`) falls back to the default rather than being partially
+ * parsed.
+ */
+export function completionInlineBudget(env = globalThis.process.env) {
+    const raw = env[COMPLETION_INLINE_BUDGET_ENV]?.trim();
+    if (raw === undefined || raw === '' || !/^\d+$/.test(raw)) {
+        return COMPLETION_INLINE_BUDGET_DEFAULT;
+    }
+    const parsed = Number(raw);
+    if (parsed <= 0) {
+        return COMPLETION_INLINE_BUDGET_DEFAULT;
+    }
+    return Math.min(parsed, COMPLETION_INLINE_BUDGET_MAX);
+}
+/**
+ * Decide whether a completion result is inlined or spilled. Spilling writes the
+ * FULL result to a 0600 file (async fs only — no sync IO, repo rule #85) under
+ * the caller-supplied `spillDir` and returns the path; the caller inlines only
+ * that path. `spillDir` is supplied by the caller, so this module stays
+ * runtime-neutral and never names a dispatcher id.
+ */
+export async function resolveCompletionBody(completion, spillDir) {
+    const budget = completionInlineBudget();
+    if (completion.result.length <= budget) {
+        return { kind: 'inline', text: completion.result };
+    }
+    const path = teamMateCompletionOutputPath(spillDir, completion.source, completion.id);
+    // Owner-only spill dir: the cache may hold full teammate output. Use the
+    // shared helper so a pre-existing permissive dir is tightened and a symlink /
+    // foreign-uid dir is rejected (issue #182 — same invariant as the run tree),
+    // then a 0600 file + explicit chmod (writeFile's `mode` honors the umask).
+    await ensureOwnerOnlyDir(spillDir);
+    await writeFile(path, completion.result, { mode: 0o600 });
+    await chmod(path, 0o600);
+    return { kind: 'spilled', path };
+}
+//# sourceMappingURL=completion-body.js.map

package/dist/completion-body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-body.js","sourceRoot":"","sources":["../src/completion-body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,MAAM,CAAC;AACvD,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AACpD,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AAM9D,uDAAuD;AACvD,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAgB,EAChB,MAAc,EACd,EAAU;IAEV,OAAO,IAAI,CAAC,QAAQ,EAAE,YAAY,WAAW,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAyB,UAAU,CAAC,OAAO,CAAC,GAAG;IAE/C,MAAM,GAAG,GAAG,GAAG,CAAC,4BAA4B,CAAC,EAAE,IAAI,EAAE,CAAC;IACtD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,4BAA4B,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,UAA8B,EAC9B,QAAgB;IAEhB,MAAM,MAAM,GAAG,sBAAsB,EAAE,CAAC;IACxC,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,4BAA4B,CACvC,QAAQ,EACR,UAAU,CAAC,MAAM,EACjB,UAAU,CAAC,EAAE,CACd,CAAC;IACF,yEAAyE;IACzE,8EAA8E;IAC9E,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;AACnC,CAAC"}

package/dist/config-validate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Neutral config validation primitives.
+ *
+ * Extracted from `config/config.ts` so that per-runtime config readers (each
+ * builtin's `agent-runtime/builtin/<name>/config.ts`) can validate their own
+ * config blocks without importing `config/config.ts` — importing the host
+ * config module from a builtin would re-form the builtin -> config import
+ * cycle. These helpers are runtime-agnostic: they only know about JSON shapes
+ * and produce `dreamux config error in <file>: ...` messages.
+ */
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function describeType(v: unknown): string;
+export declare function rejectUnknownKeys(obj: Record<string, unknown>, allowed: Set<string>, file: string, prefix: string): void;
+export declare function requireNonEmptyString(obj: Record<string, unknown>, key: string, file: string, prefix?: string): string;
+export declare function readOptionalString(obj: Record<string, unknown>, key: string, file: string, prefix?: string): string | null;
+export declare function readOptionalBoolean(obj: Record<string, unknown>, key: string, fallback: boolean, file: string, prefix?: string): boolean;
+export declare function requireStringArray(obj: Record<string, unknown>, key: string, fallback: string[], file: string, prefix?: string): string[];
+export declare function requireStringRecord(obj: Record<string, unknown>, key: string, fallback: Record<string, string>, file: string, prefix?: string): Record<string, string>;
+export declare function requirePositiveInt(obj: Record<string, unknown>, key: string, fallback: number, file: string, prefix?: string): number;
+export declare function readProviderConfigObject(rawConfig: unknown, file: string, name: string, options?: {
+    allowMissing?: boolean;
+}): Record<string, unknown>;
+//# sourceMappingURL=config-validate.d.ts.map

package/dist/config-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validate.d.ts","sourceRoot":"","sources":["../src/config-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAI/C;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,IAAI,CAgBN;AAuBD,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,MAAM,CAMR;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,MAAM,GAAG,IAAI,CAIf;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,OAAO,CAOT;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAAE,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,MAAM,EAAE,CAgBV;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkBxB;AAgBD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,SAAK,GACV,MAAM,CASR;AAED,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GACvC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB"}

package/dist/config-validate.js

@@ -0,0 +1,122 @@
+/**
+ * Neutral config validation primitives.
+ *
+ * Extracted from `config/config.ts` so that per-runtime config readers (each
+ * builtin's `agent-runtime/builtin/<name>/config.ts`) can validate their own
+ * config blocks without importing `config/config.ts` — importing the host
+ * config module from a builtin would re-form the builtin -> config import
+ * cycle. These helpers are runtime-agnostic: they only know about JSON shapes
+ * and produce `dreamux config error in <file>: ...` messages.
+ */
+export function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+export function describeType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+export function rejectUnknownKeys(obj, allowed, file, prefix) {
+    for (const key of Object.keys(obj)) {
+        if (allowed.has(key))
+            continue;
+        const name = `${prefix}${key}`;
+        if (/^dispatchers\[\d+\]\.$/.test(prefix) && (key === 'feishu' || key === 'codex')) {
+            throw new Error(`dreamux config error in ${file}: ${name} is not supported by the providerized config v2 schema.\n` +
+                'Dreamux 0.x does not silently migrate operator-owned config. Rebuild this dispatcher with ' +
+                'dispatchers[].channels[] for the channel and a named agents[] entry referenced via ' +
+                'dispatchers[].agentRuntime for the runtime, then restart.');
+        }
+        throw new Error(`dreamux config error in ${file}: ${name} is not supported by the providerized config v2 schema`);
+    }
+}
+function ensureString(v, key, file) {
+    if (typeof v !== 'string') {
+        throw new Error(`dreamux config error in ${file}: ${key} must be a string (got ${describeType(v)})`);
+    }
+    return v;
+}
+function requireString(obj, key, fallback, file, prefix = '') {
+    const v = obj[key];
+    if (v === undefined)
+        return fallback;
+    return ensureString(v, `${prefix}${key}`, file);
+}
+export function requireNonEmptyString(obj, key, file, prefix = '') {
+    const value = requireString(obj, key, '', file, prefix);
+    if (value.trim() !== '')
+        return value;
+    throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be a non-empty string`);
+}
+export function readOptionalString(obj, key, file, prefix = '') {
+    const v = obj[key];
+    if (v === undefined || v === null)
+        return null;
+    return ensureString(v, `${prefix}${key}`, file);
+}
+export function readOptionalBoolean(obj, key, fallback, file, prefix = '') {
+    const v = obj[key];
+    if (v === undefined)
+        return fallback;
+    if (typeof v === 'boolean')
+        return v;
+    throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be a boolean (got ${describeType(v)})`);
+}
+export function requireStringArray(obj, key, fallback, file, prefix = '') {
+    const v = obj[key];
+    if (v === undefined)
+        return fallback;
+    if (!Array.isArray(v)) {
+        throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be an array of strings (got ${describeType(v)})`);
+    }
+    return v.map((item, i) => {
+        if (typeof item !== 'string') {
+            throw new Error(`dreamux config error in ${file}: ${prefix}${key}[${i}] must be a string (got ${describeType(item)})`);
+        }
+        return item;
+    });
+}
+export function requireStringRecord(obj, key, fallback, file, prefix = '') {
+    const v = obj[key];
+    if (v === undefined)
+        return { ...fallback };
+    if (!isPlainObject(v)) {
+        throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be an object of strings (got ${describeType(v)})`);
+    }
+    const out = {};
+    for (const [entryKey, entryValue] of Object.entries(v)) {
+        if (typeof entryValue !== 'string') {
+            throw new Error(`dreamux config error in ${file}: ${prefix}${key}.${entryKey} must be a string (got ${describeType(entryValue)})`);
+        }
+        out[entryKey] = entryValue;
+    }
+    return out;
+}
+function readInt(obj, key, file, prefix) {
+    const v = obj[key];
+    if (v === undefined)
+        return null;
+    if (typeof v === 'number' && Number.isInteger(v))
+        return v;
+    throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be an integer (got ${describeType(v)})`);
+}
+export function requirePositiveInt(obj, key, fallback, file, prefix = '') {
+    const n = readInt(obj, key, file, prefix);
+    if (n === null)
+        return fallback;
+    if (n <= 0) {
+        throw new Error(`dreamux config error in ${file}: ${prefix}${key} must be > 0 (got ${n})`);
+    }
+    return n;
+}
+export function readProviderConfigObject(rawConfig, file, name, options = {}) {
+    if (rawConfig === undefined && options.allowMissing === true)
+        return {};
+    if (!isPlainObject(rawConfig)) {
+        throw new Error(`dreamux config error in ${file}: ${name} must be an object (got ${describeType(rawConfig)})`);
+    }
+    return rawConfig;
+}
+//# sourceMappingURL=config-validate.js.map

package/dist/config-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-validate.js","sourceRoot":"","sources":["../src/config-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAU;IACrC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IACrC,OAAO,OAAO,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,GAA4B,EAC5B,OAAoB,EACpB,IAAY,EACZ,MAAc;IAEd,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC/B,MAAM,IAAI,GAAG,GAAG,MAAM,GAAG,GAAG,EAAE,CAAC;QAC/B,IAAI,wBAAwB,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,OAAO,CAAC,EAAE,CAAC;YACnF,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,IAAI,2DAA2D;gBACjG,4FAA4F;gBAC5F,qFAAqF;gBACrF,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,IAAI,wDAAwD,CACjG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,CAAU,EAAE,GAAW,EAAE,IAAY;IACzD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,GAAG,0BAA0B,YAAY,CAAC,CAAC,CAAC,GAAG,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,aAAa,CACpB,GAA4B,EAC5B,GAAW,EACX,QAAgB,EAChB,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrC,OAAO,YAAY,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,GAA4B,EAC5B,GAAW,EACX,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,6BAA6B,CAC9E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAA4B,EAC5B,GAAW,EACX,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,YAAY,CAAC,CAAC,EAAE,GAAG,MAAM,GAAG,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAA4B,EAC5B,GAAW,EACX,QAAiB,EACjB,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACrC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,2BAA2B,YAAY,CAAC,CAAC,CAAC,GAAG,CAC9F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAA4B,EAC5B,GAAW,EACX,QAAkB,EAClB,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,qCAAqC,YAAY,CAAC,CAAC,CAAC,GAAG,CACxG,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACvB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,IAAI,CAAC,2BAA2B,YAAY,CAAC,IAAI,CAAC,GAAG,CACtG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAA4B,EAC5B,GAAW,EACX,QAAgC,EAChC,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC5C,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,sCAAsC,YAAY,CAAC,CAAC,CAAC,GAAG,CACzG,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,IAAI,QAAQ,0BAA0B,YAAY,CAAC,UAAU,CAAC,GAAG,CAClH,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,OAAO,CACd,GAA4B,EAC5B,GAAW,EACX,IAAY,EACZ,MAAc;IAEd,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,4BAA4B,YAAY,CAAC,CAAC,CAAC,GAAG,CAC/F,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,GAA4B,EAC5B,GAAW,EACX,QAAgB,EAChB,IAAY,EACZ,MAAM,GAAG,EAAE;IAEX,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAC1E,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,SAAkB,EAClB,IAAY,EACZ,IAAY,EACZ,UAAsC,EAAE;IAExC,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACxE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,KAAK,IAAI,2BAA2B,YAAY,CAAC,SAAS,CAAC,GAAG,CAC9F,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './config-validate.js';
+export * from './os.js';
+export * from './completion-body.js';
+export * from './socket-budget.js';
+export * from './turn-render.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from './config-validate.js';
+export * from './os.js';
+export * from './completion-body.js';
+export * from './socket-budget.js';
+export * from './turn-render.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/os.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic OS/filesystem utilities shared across Dreamux providers and host,
+ * vendored into this leaf package so the provider packages depend on
+ * `@excitedjs/dreamux-types` (+ this package) only and never import
+ * `@excitedjs/dreamux` core. These are platform primitives (process-group
+ * signalling, owner-only dir enforcement, empty-log cleanup, existence probe),
+ * NOT Dreamux host layout/path/socket/log contracts — those are supplied by the
+ * host through the create context and provider options.
+ */
+/** True when `pid` names a live process (EPERM counts as alive). */
+export declare function isProcessAlive(pid: number): boolean;
+/** Signal an entire process group; ESRCH/EPERM are swallowed. */
+export declare function killProcessGroup(pgid: number, signal: NodeJS.Signals | number): void;
+export interface EnsureOwnerOnlyDirOptions {
+    /** Current-user uid probe override (tests). */
+    getuid?: () => number;
+}
+/**
+ * Create/adopt a directory and guarantee the owner-only (0700) privacy
+ * invariant regardless of who created it: reject a symlink leaf, fail loud on a
+ * foreign-uid dir, and tighten any group/other permission bits.
+ */
+export declare function ensureOwnerOnlyDir(path: string, options?: EnsureOwnerOnlyDirOptions): Promise<void>;
+/**
+ * Remove `path` only if it exists and is zero bytes. Best-effort: a missing,
+ * non-empty, or busy file is left untouched and never throws.
+ */
+export declare function removeEmptyLogFile(path: string): Promise<void>;
+/** Best-effort existence probe — the async replacement for `existsSync`. */
+export declare function pathExists(path: string): Promise<boolean>;
+//# sourceMappingURL=os.d.ts.map

package/dist/os.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"os.d.ts","sourceRoot":"","sources":["../src/os.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASnD;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,GAC9B,IAAI,CASN;AAED,MAAM,WAAW,yBAAyB;IACxC,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOpE;AAED,4EAA4E;AAC5E,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D"}

package/dist/os.js

@@ -0,0 +1,82 @@
+/**
+ * Generic OS/filesystem utilities shared across Dreamux providers and host,
+ * vendored into this leaf package so the provider packages depend on
+ * `@excitedjs/dreamux-types` (+ this package) only and never import
+ * `@excitedjs/dreamux` core. These are platform primitives (process-group
+ * signalling, owner-only dir enforcement, empty-log cleanup, existence probe),
+ * NOT Dreamux host layout/path/socket/log contracts — those are supplied by the
+ * host through the create context and provider options.
+ */
+import { access, chmod, lstat, mkdir, stat, unlink } from 'node:fs/promises';
+/** True when `pid` names a live process (EPERM counts as alive). */
+export function isProcessAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        const errno = e.code;
+        return errno === 'EPERM';
+    }
+}
+/** Signal an entire process group; ESRCH/EPERM are swallowed. */
+export function killProcessGroup(pgid, signal) {
+    if (!Number.isFinite(pgid) || pgid <= 0)
+        return;
+    try {
+        process.kill(-pgid, signal);
+    }
+    catch (e) {
+        const errno = e.code;
+        if (errno === 'ESRCH' || errno === 'EPERM')
+            return;
+        throw e;
+    }
+}
+/**
+ * Create/adopt a directory and guarantee the owner-only (0700) privacy
+ * invariant regardless of who created it: reject a symlink leaf, fail loud on a
+ * foreign-uid dir, and tighten any group/other permission bits.
+ */
+export async function ensureOwnerOnlyDir(path, options = {}) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const info = await lstat(path);
+    if (info.isSymbolicLink()) {
+        throw new Error(`refusing to use Dreamux runtime directory ${path}: it is a symlink, not a real directory`);
+    }
+    const getuid = options.getuid ?? process.getuid?.bind(process);
+    if (getuid !== undefined && info.uid !== getuid()) {
+        throw new Error(`refusing to use Dreamux runtime directory ${path}: it is owned by uid ${info.uid}, ` +
+            `not the current user (uid ${getuid()})`);
+    }
+    if ((info.mode & 0o077) !== 0) {
+        await chmod(path, 0o700);
+    }
+}
+/**
+ * Remove `path` only if it exists and is zero bytes. Best-effort: a missing,
+ * non-empty, or busy file is left untouched and never throws.
+ */
+export async function removeEmptyLogFile(path) {
+    try {
+        const info = await stat(path);
+        if (info.size === 0)
+            await unlink(path);
+    }
+    catch {
+        /* best effort — missing/busy/non-empty files are left as-is */
+    }
+}
+/** Best-effort existence probe — the async replacement for `existsSync`. */
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=os.js.map

package/dist/os.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"os.js","sourceRoot":"","sources":["../src/os.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE7E,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,KAAK,GAAI,CAA2B,CAAC,IAAI,CAAC;QAChD,OAAO,KAAK,KAAK,OAAO,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,gBAAgB,CAC9B,IAAY,EACZ,MAA+B;IAE/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO;IAChD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,KAAK,GAAI,CAA2B,CAAC,IAAI,CAAC;QAChD,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,OAAO;YAAE,OAAO;QACnD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAOD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,UAAqC,EAAE;IAEvC,MAAM,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,6CAA6C,IAAI,yCAAyC,CAC3F,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/D,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,KAAK,MAAM,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,6CAA6C,IAAI,wBAAwB,IAAI,CAAC,GAAG,IAAI;YACnF,6BAA6B,MAAM,EAAE,GAAG,CAC3C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,CAAC;YAAE,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/socket-budget.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Unix-domain socket path-budget primitives (issue #209 cleanup).
+ *
+ * The kernel caps a Unix socket path at `sun_path` bytes (108 on Linux including
+ * the NUL terminator, 104 on macOS). 103 usable bytes is the safe cross-platform
+ * budget Dreamux enforces. These are pure functions with no IO and no host
+ * path-layout knowledge: a provider package that allocates its own rendezvous
+ * socket (e.g. the Codex app-server socket) uses them to pick a candidate
+ * directory whose full path fits, while Dreamux core uses the same primitives so
+ * the budget never drifts between the two.
+ */
+/** Safe cross-platform `sun_path` byte budget for a Unix-domain socket path. */
+export declare const DREAMUX_UNIX_SOCKET_PATH_MAX_BYTES = 103;
+/** Whether `path` fits the Unix-domain socket `sun_path` budget. */
+export declare function unixSocketPathFitsBudget(path: string): boolean;
+/**
+ * Return `path` if it fits the socket budget, else throw a fail-loud error
+ * naming `label`, the byte count, and the offending path.
+ */
+export declare function assertUnixSocketPathBudget(path: string, label: string): string;
+//# sourceMappingURL=socket-budget.d.ts.map

package/dist/socket-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-budget.d.ts","sourceRoot":"","sources":["../src/socket-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,eAAO,MAAM,kCAAkC,MAAM,CAAC;AAEtD,oEAAoE;AACpE,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM9E"}

package/dist/socket-budget.js

@@ -0,0 +1,28 @@
+/**
+ * Unix-domain socket path-budget primitives (issue #209 cleanup).
+ *
+ * The kernel caps a Unix socket path at `sun_path` bytes (108 on Linux including
+ * the NUL terminator, 104 on macOS). 103 usable bytes is the safe cross-platform
+ * budget Dreamux enforces. These are pure functions with no IO and no host
+ * path-layout knowledge: a provider package that allocates its own rendezvous
+ * socket (e.g. the Codex app-server socket) uses them to pick a candidate
+ * directory whose full path fits, while Dreamux core uses the same primitives so
+ * the budget never drifts between the two.
+ */
+/** Safe cross-platform `sun_path` byte budget for a Unix-domain socket path. */
+export const DREAMUX_UNIX_SOCKET_PATH_MAX_BYTES = 103;
+/** Whether `path` fits the Unix-domain socket `sun_path` budget. */
+export function unixSocketPathFitsBudget(path) {
+    return Buffer.byteLength(path, 'utf8') <= DREAMUX_UNIX_SOCKET_PATH_MAX_BYTES;
+}
+/**
+ * Return `path` if it fits the socket budget, else throw a fail-loud error
+ * naming `label`, the byte count, and the offending path.
+ */
+export function assertUnixSocketPathBudget(path, label) {
+    if (unixSocketPathFitsBudget(path))
+        return path;
+    const bytes = Buffer.byteLength(path, 'utf8');
+    throw new Error(`${label} is too long for Unix sockets (${bytes} bytes > ${DREAMUX_UNIX_SOCKET_PATH_MAX_BYTES} safe bytes): ${path}`);
+}
+//# sourceMappingURL=socket-budget.js.map

package/dist/socket-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-budget.js","sourceRoot":"","sources":["../src/socket-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AAEtD,oEAAoE;AACpE,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,kCAAkC,CAAC;AAC/E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAY,EAAE,KAAa;IACpE,IAAI,wBAAwB,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,kCAAkC,KAAK,YAAY,kCAAkC,iBAAiB,IAAI,EAAE,CACrH,CAAC;AACJ,CAAC"}

package/dist/turn-render.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Inbound-turn render helpers. The data shapes are published by
+ * `@excitedjs/dreamux-types`; these executable helpers render a neutral
+ * `InboundTurnInput` into runtime delivery text. Shared by every runtime and
+ * the host, vendored into this leaf package so the provider packages never
+ * import `@excitedjs/dreamux` core.
+ */
+import type { InboundTurnInput } from '@excitedjs/dreamux-types';
+export declare const DEFAULT_MESSAGE_ID_DEDUPE_WINDOW = 1024;
+/**
+ * Wrap a channel turn body in the native `<channel source="…" …>` envelope.
+ * Only safe attribute keys (`^[a-zA-Z_][a-zA-Z0-9_]*$`) are rendered and every
+ * value is XML-escaped.
+ */
+export declare function renderChannelBlock(source: string, attrs: ReadonlyArray<readonly [string, string]>, body: string): string;
+/**
+ * Render an inbound turn to delivery text. A channel-structured input (both
+ * `attrs` and `body` present) is wrapped into the `<channel>` block; a plain
+ * input (e.g. a system trigger turn) passes its `text` through unchanged.
+ */
+export declare function renderChannelInput(input: InboundTurnInput): string;
+//# sourceMappingURL=turn-render.d.ts.map

package/dist/turn-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-render.d.ts","sourceRoot":"","sources":["../src/turn-render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAYrD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC/C,IAAI,EAAE,MAAM,GACX,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAKlE"}

package/dist/turn-render.js

@@ -0,0 +1,40 @@
+/**
+ * Inbound-turn render helpers. The data shapes are published by
+ * `@excitedjs/dreamux-types`; these executable helpers render a neutral
+ * `InboundTurnInput` into runtime delivery text. Shared by every runtime and
+ * the host, vendored into this leaf package so the provider packages never
+ * import `@excitedjs/dreamux` core.
+ */
+export const DEFAULT_MESSAGE_ID_DEDUPE_WINDOW = 1024;
+const SAFE_CHANNEL_ATTR_KEY = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function escapeChannelAttr(value) {
+    return value
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+/**
+ * Wrap a channel turn body in the native `<channel source="…" …>` envelope.
+ * Only safe attribute keys (`^[a-zA-Z_][a-zA-Z0-9_]*$`) are rendered and every
+ * value is XML-escaped.
+ */
+export function renderChannelBlock(source, attrs, body) {
+    const rendered = attrs
+        .filter(([key]) => SAFE_CHANNEL_ATTR_KEY.test(key))
+        .map(([key, value]) => ` ${key}="${escapeChannelAttr(value)}"`)
+        .join('');
+    return `<channel source="${escapeChannelAttr(source)}"${rendered}>\n${body}\n</channel>`;
+}
+/**
+ * Render an inbound turn to delivery text. A channel-structured input (both
+ * `attrs` and `body` present) is wrapped into the `<channel>` block; a plain
+ * input (e.g. a system trigger turn) passes its `text` through unchanged.
+ */
+export function renderChannelInput(input) {
+    if (input.attrs === undefined || input.body === undefined) {
+        return input.text;
+    }
+    return renderChannelBlock(input.source ?? 'channel', input.attrs, input.body);
+}
+//# sourceMappingURL=turn-render.js.map

package/dist/turn-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-render.js","sourceRoot":"","sources":["../src/turn-render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAErD,MAAM,qBAAqB,GAAG,0BAA0B,CAAC;AAEzD,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAAc,EACd,KAA+C,EAC/C,IAAY;IAEZ,MAAM,QAAQ,GAAG,KAAK;SACnB,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAClD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC;SAC9D,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,oBAAoB,iBAAiB,CAAC,MAAM,CAAC,IAAI,QAAQ,MAAM,IAAI,cAAc,CAAC;AAC3F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,kBAAkB,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;AAChF,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@excitedjs/dreamux-utils",
+  "version": "0.1.1-alpha.g0ddd418597ca",
+  "description": "Pure shared utilities for Dreamux providers and host: neutral config-validation primitives, OS/filesystem helpers, completion-body resolution, and inbound-turn render helpers. Depends on @excitedjs/dreamux-types only, never on @excitedjs/dreamux core (issue excitedjs/dreamux#209).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/excitedjs/dreamux.git",
+    "directory": "packages/dreamux-utils"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.7"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@excitedjs/dreamux-types": "0.2.0-alpha.g0ddd418597ca"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "eslint": "^9.39.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "@excitedjs/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}