toolnexus 0.18.1 → 0.20.0

package/dist/client.js

@@ -2,6 +2,75 @@ import { pendingOf } from "./types.js";
 import { isRetryableStatus, retryAfterMs } from "./retry.js";
 import { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
+/**
+ * The §8 CLIENT status vocabulary, as a value. It is a DIFFERENT, smaller closed set than the
+ * §7D AGENT vocabulary (`agents.TASK_STATUSES`), which also contains `"timeout"`, `"closed"`,
+ * `"interrupted"` and `"error"`. Two fields are called `status`; they are not interchangeable.
+ * A run that fails at a deadline THROWS here — it never comes back as a `RunResult`.
+ */
+export const RUN_STATUSES = ["done", "pending", "incomplete"];
+/** Account-identifier keys blanked out of a provider error body before it reaches a message,
+ *  a log or a metric. The shape survives; the value does not (ADR 0027 D3.2). */
+export const REDACTED_BODY_KEYS = ["user_id", "account_id", "org_id", "organization"];
+/** What a redacted value is replaced with — identical in all seven ports. */
+export const REDACTION_PLACEHOLDER = "\u00abredacted\u00bb";
+/** A redacted body is capped at this many characters IN THE MESSAGE ONLY. The typed `body`
+ *  field carries the full redacted body — a host that opted into a typed error asked for the
+ *  whole thing (ADR 0027 D3 / addendum A5). */
+export const ERROR_BODY_CAP = 200;
+/**
+ * Redact known account identifiers, then cap. A CAP IS NOT REDACTION: the body that leaked
+ * `user_2…` in issue #92 was 96 bytes, well inside the cap, so both steps are needed and
+ * redaction runs FIRST (capping first could split a key/value pair and hide it from the regex).
+ */
+export function redactErrorBody(body) {
+    let out = body;
+    for (const key of REDACTED_BODY_KEYS) {
+        // JSON ("key": "value" / "key": 123) and form/query (key=value) spellings alike.
+        out = out.replace(new RegExp(`("${key}"\\s*:\\s*)("(?:[^"\\\\]|\\\\.)*"|-?\\d+(?:\\.\\d+)?|true|false|null)`, "g"), `$1"${REDACTION_PLACEHOLDER}"`);
+        out = out.replace(new RegExp(`\\b${key}=([^&\\s]+)`, "g"), `${key}=${REDACTION_PLACEHOLDER}`);
+    }
+    return out.trim();
+}
+/** Cap a already-redacted body for interpolation into a MESSAGE. Redaction is not a cap and a
+ *  cap is not redaction: they are independent and both are needed. */
+export function capErrorBody(body) {
+    return body.length > ERROR_BODY_CAP ? body.slice(0, ERROR_BODY_CAP) + "\u2026" : body;
+}
+/**
+ * A provider failure carried as a VALUE, not a sentence (ADR 0027 D3.1). A host that must
+ * decide what to log can read `status` / `retryAfter` instead of parsing a message.
+ *
+ * `body` is ALREADY redacted and capped, and is `""` on 401/403 — an auth body routinely
+ * reflects the credential or the header that was sent. `rawBody` is never populated by the
+ * library; the SPEC credentials guarantee now covers error messages too.
+ */
+export class LlmHttpError extends Error {
+    status;
+    body;
+    retryAfter;
+    name = "LlmHttpError";
+    constructor(
+    /** The HTTP status the provider answered with. */
+    status, 
+    /** The provider's FULL redacted body; `""` on 401/403 and when empty. Uncapped — the cap
+     *  applies to `message` only. */
+    body, 
+    /** The `Retry-After` header verbatim, when the provider sent one. */
+    retryAfter) {
+        super(`LLM ${status}${body ? ": " + capErrorBody(body) : ""}`);
+        this.status = status;
+        this.body = body;
+        this.retryAfter = retryAfter;
+    }
+}
+/** Build the typed error from a non-2xx provider response (reads the body once). */
+export async function llmHttpError(res) {
+    const raw = await res.text().catch(() => "");
+    // 401/403: never echo the body — see `Classifier.cause`, now one policy, not two.
+    const body = res.status === 401 || res.status === 403 ? "" : redactErrorBody(raw);
+    return new LlmHttpError(res.status, body, res.headers.get("retry-after") ?? undefined);
+}
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -229,11 +298,17 @@ export class Client {
     emitRunError(runStart, toolCalls, turns, usage, e) {
         this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) });
     }
+    /**
+     * Run the loop. `ctx` — and `ctx.toolkit` inside it — are OPTIONAL: an absent toolkit is a
+     * COMPLETION (SPEC §0.10). The system message is then the system prompt alone, and the
+     * request body carries no `tools` and no `tool_choice` key (not an empty array). An empty
+     * toolkit and no toolkit are observably identical on the wire.
+     */
     async run(prompt, ctx) {
         checkPromptParts(prompt, this.wireOpts());
         return this.opts.style === "anthropic"
-            ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
-            : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history);
+            ? this.runAnthropic(prompt, ctx?.toolkit, ctx?.signal, ctx?.history)
+            : this.runOpenAI(prompt, ctx?.toolkit, ctx?.signal, ctx?.history);
     }
     /**
      * Single-turn translation (§11): exactly ONE provider call, returned in OpenAI shape.
@@ -274,7 +349,7 @@ export class Client {
         if (req.maxTokens)
             body.max_tokens = req.maxTokens;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
@@ -299,6 +374,9 @@ export class Client {
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /** Anthropic-style upstream: the real translation. */
     async translateAnthropic(req) {
@@ -332,7 +410,7 @@ export class Client {
         if (tc)
             body.tool_choice = tc;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(endpoint, {
                 method: "POST",
                 headers: {
@@ -369,6 +447,9 @@ export class Client {
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /**
      * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
@@ -390,7 +471,7 @@ export class Client {
     async ask(prompt, ctx) {
         // Block-style streaming: run the streaming loop, forward text deltas, still return the
         // final RunResult. Memory (id load/save) is handled by stream() itself, so no duplication.
-        if (ctx.on_text) {
+        if (ctx?.on_text) {
             let result;
             for await (const ev of this.stream(prompt, { toolkit: ctx.toolkit, id: ctx.id, signal: ctx.signal })) {
                 if (ev.type === "text")
@@ -400,8 +481,8 @@ export class Client {
             }
             return result;
         }
-        if (!ctx.id)
-            return this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal });
+        if (!ctx?.id)
+            return this.run(prompt, { toolkit: ctx?.toolkit, signal: ctx?.signal });
         const history = (await this.store.get(ctx.id)) ?? [];
         const result = await this.run(prompt, { toolkit: ctx.toolkit, signal: ctx.signal, history });
         await this.store.save(ctx.id, result.messages);
@@ -409,7 +490,7 @@ export class Client {
     }
     /** A stateful multi-turn conversation that retains history across sends. */
     conversation(ctx) {
-        return new Conversation(this, ctx.toolkit, ctx.signal);
+        return new Conversation(this, ctx?.toolkit, ctx?.signal);
     }
     /**
      * Streaming variant: async-iterate live events (text deltas, tool calls/results, usage, done).
@@ -418,25 +499,43 @@ export class Client {
      */
     async *stream(prompt, ctx) {
         checkPromptParts(prompt, this.wireOpts());
-        const history = ctx.id ? (await this.store.get(ctx.id)) ?? [] : undefined;
+        const history = ctx?.id ? (await this.store.get(ctx.id)) ?? [] : undefined;
         const gen = this.opts.style === "anthropic"
-            ? this.streamAnthropic(prompt, ctx.toolkit, ctx.signal, history)
-            : this.streamOpenAI(prompt, ctx.toolkit, ctx.signal, history);
+            ? this.streamAnthropic(prompt, ctx?.toolkit, ctx?.signal, history)
+            : this.streamOpenAI(prompt, ctx?.toolkit, ctx?.signal, history);
         for await (const ev of gen) {
-            if (ev.type === "done" && ctx.id)
+            if (ev.type === "done" && ctx?.id)
                 await this.store.save(ctx.id, ev.result.messages);
             yield ev;
         }
     }
+    /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
+     *  the system message is the system prompt alone. This deref was issue #86 (ADR 0023). */
     system(toolkit) {
-        return [this.opts.systemPrompt ?? "", toolkit.skillsPrompt()].filter(Boolean).join("\n\n");
+        return [this.opts.systemPrompt ?? "", toolkit?.skillsPrompt() ?? ""].filter(Boolean).join("\n\n");
     }
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    runTimers = new WeakMap();
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    releaseSignal(signal) {
+        const t = this.runTimers.get(signal);
+        if (t !== undefined) {
+            clearTimeout(t);
+            this.runTimers.delete(signal);
+        }
+    }
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     makeSignal(external) {
         const ctrl = new AbortController();
         if (this.opts.timeoutMs) {
             const t = setTimeout(() => ctrl.abort(new Error(`run timeout after ${this.opts.timeoutMs}ms`)), this.opts.timeoutMs);
-            t.unref?.();
+            this.runTimers.set(ctrl.signal, t);
         }
         if (external) {
             if (external.aborted)
@@ -484,7 +583,7 @@ export class Client {
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     async runTool(toolkit, name, args, id, turn) {
         const h = this.opts.hooks;
-        const source = toolkit.get(name)?.source ?? "custom";
+        const source = toolkit?.get(name)?.source ?? "custom";
         const t0 = Date.now();
         let a = args;
         if (h?.beforeTool) {
@@ -498,7 +597,10 @@ export class Client {
             if (ov?.args)
                 a = ov.args;
         }
-        let result = await toolkit.execute(name, a);
+        // No toolkit ⇒ nothing was declared, so a tool call is the provider inventing one.
+        let result = toolkit
+            ? await toolkit.execute(name, a)
+            : { output: `unknown tool: ${name}`, isError: true };
         // A suspension (§10) is not a real result: skip afterTool's failure path on it — the resolved
         // result (post-waitFor) still flows through afterTool in resolvePending — and never count it as
         // a tool error.
@@ -521,7 +623,7 @@ export class Client {
         try {
             const res = await this.llmFetch(url, init, signal);
             if (!res.ok)
-                throw new Error(`LLM ${res.status}: ${await res.text()}`);
+                throw await llmHttpError(res);
             const data = await res.json();
             const tok = perCall(data.usage, style);
             this.emit({ event: "llm", model: this.opts.model, status: "ok", ms: Date.now() - t0, promptTokens: tok.prompt, completionTokens: tok.completion });
@@ -532,10 +634,47 @@ export class Client {
             throw e;
         }
     }
-    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    // The run-scoped timeout timer is owned by these four wrappers, so it is cleared however the
+    // run leaves: return, throw, or a consumer abandoning the stream half-way.
     async runOpenAI(prompt, toolkit, external, history) {
-        const key = resolveKey(this.opts);
         const signal = this.makeSignal(external);
+        try {
+            return await this.runOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async runAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            return await this.runAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamOpenAI(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    async runOpenAIWithSignal(signal, prompt, toolkit, history) {
+        const key = resolveKey(this.opts);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -544,7 +683,7 @@ export class Client {
                 messages.push({ role: "system", content: system });
         }
         messages.push({ role: "user", content: prompt });
-        let tools = toolkit.toOpenAI();
+        let tools = toolkit?.toOpenAI() ?? [];
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
@@ -624,27 +763,28 @@ export class Client {
         if (!answer?.ok)
             return { result: { output: `declined/expired: ${request.prompt}`, isError: true } };
         const t0 = Date.now();
-        let result = await toolkit.execute(name, args, { answer });
+        let result = toolkit
+            ? await toolkit.execute(name, args, { answer })
+            : { output: `unknown tool: ${name}`, isError: true };
         if (this.opts.hooks?.afterTool) {
             const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn });
             if (ov?.result)
                 result = ov.result;
         }
-        this.emitTool(name, toolkit.get(name)?.source ?? "custom", result, t0);
+        this.emitTool(name, toolkit?.get(name)?.source ?? "custom", result, t0);
         if (pendingOf(result))
             result = { output: `unresolved: ${request.prompt}`, isError: true }; // never loop forever
         return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
-    async runAnthropic(prompt, toolkit, external, history) {
+    async runAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
         const runStart = Date.now();
         let messages = history && history.length ? [...history, { role: "user", content: prompt }] : [{ role: "user", content: prompt }];
-        let tools = toolkit.toAnthropic();
+        let tools = toolkit?.toAnthropic() ?? [];
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
@@ -714,9 +854,8 @@ export class Client {
         }
     }
     // ---- Streaming: OpenAI-style ----
-    async *streamOpenAI(prompt, toolkit, external, history) {
+    async *streamOpenAIWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -725,7 +864,7 @@ export class Client {
                 messages.push({ role: "system", content: system });
         }
         messages.push({ role: "user", content: prompt });
-        let tools = toolkit.toOpenAI();
+        let tools = toolkit?.toOpenAI() ?? [];
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
@@ -750,7 +889,7 @@ export class Client {
                         body: JSON.stringify(this.openaiBody(messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
-                        throw new Error(`LLM ${res.status}: ${await res.text()}`);
+                        throw await llmHttpError(res);
                     for await (const line of sseLines(res.body)) {
                         if (!line.startsWith("data:"))
                             continue;
@@ -824,15 +963,14 @@ export class Client {
         }
     }
     // ---- Streaming: Anthropic-style ----
-    async *streamAnthropic(prompt, toolkit, external, history) {
+    async *streamAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
         let messages = history && history.length ? [...history, { role: "user", content: prompt }] : [{ role: "user", content: prompt }];
-        let tools = toolkit.toAnthropic();
+        let tools = toolkit?.toAnthropic() ?? [];
         const toolCalls = [];
         const usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
         let turns = 0;
@@ -857,7 +995,7 @@ export class Client {
                         body: JSON.stringify(this.anthropicBody(system, messages, tools, true)),
                     }, signal);
                     if (!res.ok || !res.body)
-                        throw new Error(`LLM ${res.status}: ${await res.text()}`);
+                        throw await llmHttpError(res);
                     for await (const line of sseLines(res.body)) {
                         if (!line.startsWith("data:"))
                             continue;
@@ -942,19 +1080,18 @@ export function createClient(opts) {
  *  name can never resolve. */
 const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
 /**
- * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
- * HTTP types to construct.
- *
- * This is a second constructor, not a second seam: it builds on the same injectable
- * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
- * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
+ * the reusable piece of {@link createInProcessClient} — assembles the wire request,
+ * calls `generate`, and re-encodes its answer as an OpenAI-shaped `Response`. Every
+ * caller that wants an in-process model behind a `fetch` slot (the top-level client,
+ * or the agent runtime's `inProcess` option) goes through this ONE function, so there
+ * is no second copy of the request/response assembly to drift.
  *
  * Streaming is refused rather than faked — see the thrown error.
  */
-export function createInProcessClient(opts) {
-    const { generate, ...rest } = opts;
+export function createInProcessFetch(generate) {
     if (typeof generate !== "function") {
-        throw new Error("toolnexus: createInProcessClient requires a `generate` function");
+        throw new Error("toolnexus: createInProcessFetch requires a `generate` function");
     }
     const inProcessFetch = async (_url, init) => {
         const body = JSON.parse(String(init?.body ?? "{}"));
@@ -999,6 +1136,23 @@ export function createInProcessClient(opts) {
             },
         }), { status: 200, headers: { "content-type": "application/json" } });
     };
+    return inProcessFetch;
+}
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * This is a second constructor, not a second seam: it builds on the same injectable
+ * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
+ * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
+ * is just that adapter wired into a `Client`.
+ *
+ * Streaming is refused rather than faked — see {@link createInProcessFetch}.
+ */
+export function createInProcessClient(opts) {
+    const { generate, ...rest } = opts;
+    const inProcessFetch = createInProcessFetch(generate);
     return new Client({
         // Retries default to ZERO here, unlike a network client. There is no wire, so
         // there is no transient failure to ride out: whatever `generate` throws will

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./builtin.js";
 export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
+export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./adapters.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./builtin.js";
 export * from "./native.js";
 export * from "./http.js";
 export * from "./a2a.js";
+export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
 export * from "./adapters.js";

package/dist/order.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Deterministic ordering for everything the library lists (addenda A1a, A15, A22, A24).
+ *
+ * INTERNAL — deliberately not re-exported from `index.ts`. These are not API; they are the one
+ * place the ordering rules live so no caller has to remember them.
+ *
+ * The rules, and why each exists:
+ *
+ *  - **Never `localeCompare`.** It orders by the machine's ICU data, so the same build emits a
+ *    different order on a different machine. A cross-port byte-identity claim cannot survive it.
+ *  - **Never a bare `Array.sort()`.** JS's default compares UTF-16 CODE UNITS, which disagrees
+ *    with code point above U+FFFF — the same divergence C#'s `StringComparer.Ordinal` has.
+ *  - **Never an ABSENT sort over a directory read.** `readdirSync` is sorted on most platforms,
+ *    but Node guarantees nothing, and a walk that breaks at a cap turns that accident into a
+ *    CONTENT difference: which files appear, not merely their order.
+ */
+/**
+ * Unicode CODE-POINT comparison — the one string ordering rule, identical in all seven ports.
+ * Iterates code points rather than code units, so a surrogate pair sorts after U+E000–U+FFFF
+ * (where `<`, `Array.sort()` and `StringComparer.Ordinal` all disagree with it).
+ */
+export declare function compareCodePoints(a: string, b: string): number;
+/**
+ * The SKILL DISCOVERY order (addendum A15): DEPTH (path segments) ascending, then code point,
+ * over a path relative to the root. First-wins then keeps the shallowest copy of a duplicated
+ * name, uniformly — code point alone makes the winner depend on the skill's own first letter
+ * (`docx` beats `synced/…`, but `xlsx` loses to it).
+ */
+export declare function compareDiscovery(a: string, b: string, sep: string): number;
+/**
+ * Sort a directory's entries BY NAME, in code-point order, in place.
+ *
+ * By NAME at each level, never by full path: that is what makes ports walking the same tree with
+ * the same stack produce the same sequence, which matters because a capped walk's cap decides
+ * WHICH entries are reached.
+ */
+export declare function sortEntriesByName<T extends {
+    name: string;
+}>(entries: T[]): T[];
+/**
+ * The listing path form (addendum A28): a relative path with `/` as the separator ON EVERY
+ * PLATFORM. Every capped or ordered listing EMITS this string and SORTS ON THE SAME STRING —
+ * ordering by one thing and showing another is how a listing ends up looking unsorted to its
+ * reader while passing its own test. Takes an already-relative path (`path.relative(...)`).
+ */
+export declare function toPosixPath(rel: string, sep: string): string;

package/dist/order.js

@@ -0,0 +1,71 @@
+/**
+ * Deterministic ordering for everything the library lists (addenda A1a, A15, A22, A24).
+ *
+ * INTERNAL — deliberately not re-exported from `index.ts`. These are not API; they are the one
+ * place the ordering rules live so no caller has to remember them.
+ *
+ * The rules, and why each exists:
+ *
+ *  - **Never `localeCompare`.** It orders by the machine's ICU data, so the same build emits a
+ *    different order on a different machine. A cross-port byte-identity claim cannot survive it.
+ *  - **Never a bare `Array.sort()`.** JS's default compares UTF-16 CODE UNITS, which disagrees
+ *    with code point above U+FFFF — the same divergence C#'s `StringComparer.Ordinal` has.
+ *  - **Never an ABSENT sort over a directory read.** `readdirSync` is sorted on most platforms,
+ *    but Node guarantees nothing, and a walk that breaks at a cap turns that accident into a
+ *    CONTENT difference: which files appear, not merely their order.
+ */
+/**
+ * Unicode CODE-POINT comparison — the one string ordering rule, identical in all seven ports.
+ * Iterates code points rather than code units, so a surrogate pair sorts after U+E000–U+FFFF
+ * (where `<`, `Array.sort()` and `StringComparer.Ordinal` all disagree with it).
+ */
+export function compareCodePoints(a, b) {
+    if (a === b)
+        return 0;
+    const ai = a[Symbol.iterator]();
+    const bi = b[Symbol.iterator]();
+    for (;;) {
+        const x = ai.next();
+        const y = bi.next();
+        if (x.done)
+            return y.done ? 0 : -1;
+        if (y.done)
+            return 1;
+        const cx = x.value.codePointAt(0);
+        const cy = y.value.codePointAt(0);
+        if (cx !== cy)
+            return cx < cy ? -1 : 1;
+    }
+}
+/**
+ * The SKILL DISCOVERY order (addendum A15): DEPTH (path segments) ascending, then code point,
+ * over a path relative to the root. First-wins then keeps the shallowest copy of a duplicated
+ * name, uniformly — code point alone makes the winner depend on the skill's own first letter
+ * (`docx` beats `synced/…`, but `xlsx` loses to it).
+ */
+export function compareDiscovery(a, b, sep) {
+    const da = a.split(sep).length;
+    const db = b.split(sep).length;
+    if (da !== db)
+        return da < db ? -1 : 1;
+    return compareCodePoints(a, b);
+}
+/**
+ * Sort a directory's entries BY NAME, in code-point order, in place.
+ *
+ * By NAME at each level, never by full path: that is what makes ports walking the same tree with
+ * the same stack produce the same sequence, which matters because a capped walk's cap decides
+ * WHICH entries are reached.
+ */
+export function sortEntriesByName(entries) {
+    return entries.sort((x, y) => compareCodePoints(x.name, y.name));
+}
+/**
+ * The listing path form (addendum A28): a relative path with `/` as the separator ON EVERY
+ * PLATFORM. Every capped or ordered listing EMITS this string and SORTS ON THE SAME STRING —
+ * ordering by one thing and showing another is how a listing ends up looking unsorted to its
+ * reader while passing its own test. Takes an already-relative path (`path.relative(...)`).
+ */
+export function toPosixPath(rel, sep) {
+    return sep === "/" ? rel : rel.split(sep).join("/");
+}

package/dist/skill.d.ts

@@ -32,6 +32,12 @@ export type SkillSkipReason = "missing-name" | "malformed-frontmatter" | "duplic
 export interface SkillSkip {
     location: string;
     reason: SkillSkipReason;
+    /**
+     * The NATIVE parser's own message ("Tabs are not allowed as indentation at line 3"), which is
+     * one keystroke from fixed and used to be discarded. Kept as a SEPARATE field so `reason`
+     * stays byte-identical across ports while this stays native — never compare it for parity.
+     */
+    detail?: string;
 }
 /** Result of a list-only validate pass (SPEC.md §3, S3). */
 export interface SkillInventory {
@@ -52,6 +58,13 @@ export interface SkillSource {
     tool: Tool;
     /** Markdown catalog for the system prompt (mirrors opencode Skill.fmt). */
     prompt(): string;
+    /**
+     * Candidate SKILL.md files that did NOT become skills, with the typed reason and the native
+     * parser `detail` (ADR 0028). Previously only `listSkills` reported these, so the path every
+     * README and example uses — `loadSkills` — could load 69 of 75 and say nothing. An omission
+     * that stops being reported is indistinguishable from something that was finished.
+     */
+    skipped: SkillSkip[];
 }
 /**
  * Discover + validate skills from the same sources loadSkills accepts, returning