@zenera/neo 1.1.10 → 1.1.12

package/dist/failure.js

@@ -0,0 +1,323 @@
+import { classify, isAbort, statusOf } from "./embeddings/rate-limit.js";
+export const callSites = (model, provider) => (doing, api) => ({ doing, api, model, provider });
+const ONCE = { attempts: 1, elapsedMs: 0 };
+/** A provider call that failed, with the call it was. */
+export class ProviderError extends Error {
+    site;
+    /** the vendor's own sentence, unwrapped out of whatever it arrived in */
+    detail;
+    /** the HTTP status, wherever the SDK or the body left it */
+    status;
+    attempts;
+    elapsedMs;
+    chunks;
+    constructor(site, detail, status, cause, tried = ONCE) {
+        super(`${site.doing} failed — ${where(site)}: ${detail}${trailer(tried)}`, { cause });
+        this.name = 'ProviderError';
+        this.site = site;
+        this.detail = detail;
+        this.status = status;
+        this.attempts = tried.attempts;
+        this.elapsedMs = tried.elapsedMs;
+        this.chunks = tried.chunks;
+    }
+}
+/**
+ * What the failure cost, when that is worth a person's attention. A call that
+ * failed at once and was never retried spent nothing worth reporting, and the
+ * message is long already.
+ */
+function trailer(tried) {
+    const said = [];
+    if (tried.attempts > 1) {
+        said.push(`${tried.attempts} attempts`);
+    }
+    if (tried.elapsedMs >= 1_000) {
+        said.push(`${(tried.elapsedMs / 1000).toFixed(1)}s`);
+    }
+    if (tried.chunks) {
+        // Says why it was not retried, which is the first thing asked of a
+        // connection that dropped.
+        const many = tried.chunks === 1 ? '' : 's';
+        said.push(`${tried.chunks} chunk${many} in, too late to retry`);
+    }
+    return said.length ? ` [after ${said.join(', ')}]` : '';
+}
+const where = (site) => `${site.provider ? `${site.provider} ` : ''}${site.api}, model "${site.model}"`;
+/** Runs one provider call, and makes sure a refusal says what it refused. */
+export async function called(site, run) {
+    const started = Date.now();
+    try {
+        return await run();
+    }
+    catch (err) {
+        // The SDK's own retries are inside this: an OpenAI or Vertex client
+        // gives up only after four of them, so the elapsed time is the only
+        // report of what the wait was spent on.
+        throw failed(site, err, { attempts: 1, elapsedMs: Date.now() - started });
+    }
+}
+/**
+ * Attempts to reopen a stream that broke before it said anything, and the pause
+ * before each. Short on purpose: the client's own backoff has already been
+ * spent getting the request accepted, and a body that dies on an accepted
+ * connection is usually a dropped socket rather than a busy server.
+ */
+const REOPEN = 2;
+const REOPEN_BACKOFF_MS = 300;
+/**
+ * The same for a response body: an HTTP error, and every mid-stream failure,
+ * arrives while the stream is being read — long after the call that opened it
+ * returned successfully. None of the SDKs retry that: their backoff wraps the
+ * request, and by the time a body is being consumed the request has succeeded.
+ *
+ * So this does, but only while nothing has come out of it. A connection reset
+ * before the first chunk is indistinguishable from one that never opened, and
+ * reopening is invisible to the caller. One chunk later it is not: the deltas
+ * have been delivered, a second stream would repeat them, and the failure has
+ * to be reported instead.
+ */
+export async function* reading(site, source, reopen) {
+    const started = Date.now();
+    let stream = source;
+    let chunks = 0;
+    for (let attempt = 1;; attempt++) {
+        try {
+            for await (const item of stream) {
+                chunks++;
+                yield item;
+            }
+            return;
+        }
+        catch (err) {
+            const again = reopen &&
+                chunks === 0 &&
+                attempt <= REOPEN &&
+                !isAbort(err) &&
+                classify(err) !== 'fatal';
+            if (!again) {
+                throw failed(site, err, {
+                    attempts: attempt,
+                    elapsedMs: Date.now() - started,
+                    chunks,
+                });
+            }
+            await sleep(REOPEN_BACKOFF_MS * attempt);
+            stream = await reopen();
+        }
+    }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** Names for "the caller stopped waiting", which are not the provider's doing. */
+const INTERRUPTED = new Set(['AbortError', 'TimeoutError']);
+/** The error to throw in place of `err`, which may be `err` itself. */
+export function failed(site, err, tried = ONCE) {
+    // An abort is the caller's own decision and a deadline is the caller's own
+    // clock. Both are recognised by name upstream, so neither is rewritten.
+    const name = err?.name;
+    if (err instanceof ProviderError ||
+        isAbort(err) ||
+        (typeof name === 'string' && INTERRUPTED.has(name))) {
+        return err;
+    }
+    const { detail, status } = explain(err);
+    return new ProviderError(site, detail, status, err, tried);
+}
+/** Bodies nest at most this deep before the unwrapping is the bug. */
+const MAX_UNWRAP = 4;
+/** Words that name a category of failure without naming the failure. */
+const OPAQUE = /^(fetch failed|failed to fetch|terminated|internal error)\.?$/i;
+/** Longer than this is a document, not a sentence. */
+const MAX_DETAIL = 500;
+/**
+ * The sentence a vendor buried, and the status it came with. Exported because
+ * it is useful anywhere a raw provider error has to be shown to someone.
+ */
+export function explain(err) {
+    let status = statusOf(err);
+    let code;
+    let about;
+    let text = messageOf(err);
+    // Unwrapping once is not enough — Google's body holds a body — and
+    // unwrapping until it stops is a loop waiting for a self-quoting error.
+    for (let depth = 0; depth < MAX_UNWRAP; depth++) {
+        const said = body(text);
+        if (!said) {
+            break;
+        }
+        // The innermost wins: the outer layer says `Bad Request`, the inner one
+        // says which argument was invalid.
+        status = said.status ?? status;
+        code = said.code ?? code;
+        about = said.about ?? about;
+        text = said.message;
+    }
+    code ??= symbolOf(err);
+    // A failure raised from inside a stream has no HTTP status to carry: the
+    // response was a 200 and the refusal arrived as an event in it. The vendor's
+    // own word for what went wrong is the only thing left to classify on, and
+    // everything downstream — the retry limiter, the CLI's liveness probe —
+    // classifies on the status.
+    status ??= code ? STATUS.get(code.toLowerCase()) : undefined;
+    // `Request contains an invalid argument` names no argument. The vendor's
+    // `details` are where the field that was wrong is, when it is anywhere.
+    text = collapse(about ? `${text.trim()} — ${about}` : text);
+    if (!text || OPAQUE.test(text)) {
+        // `fetch failed` is undici's word for DNS, refused, TLS and timeout
+        // alike; the reason is only ever in the cause.
+        const because = blamed(err, text);
+        text = because ? (text ? `${text} — ${because}` : because) : text;
+    }
+    return { detail: mark(text || String(err), status, code), status };
+}
+const messageOf = (err) => err instanceof Error ? err.message : typeof err === 'string' ? err : String(err);
+/** The vendor's word for the kind of refusal, off the error object itself. */
+function symbolOf(err) {
+    for (const link of chain(err)) {
+        for (const key of ['code', 'type']) {
+            const said = link[key];
+            if (typeof said === 'string' && said) {
+                return said;
+            }
+        }
+    }
+    return undefined;
+}
+/** The error and everything it blames, guarded against a self-referential cause. */
+function* chain(err) {
+    const seen = new Set();
+    for (let at = err; at && typeof at === 'object' && !seen.has(at); at = cause(at)) {
+        seen.add(at);
+        yield at;
+    }
+}
+const cause = (err) => err.cause;
+/**
+ * What a symbolic refusal would have been as an HTTP status, for the vendors
+ * that omit one. Only the unambiguous ones: a guess here is a retry decision.
+ */
+const STATUS = new Map([
+    ['invalid_request_error', 400],
+    ['invalid_argument', 400],
+    ['context_length_exceeded', 400],
+    ['authentication_error', 401],
+    ['unauthenticated', 401],
+    ['permission_error', 403],
+    ['permission_denied', 403],
+    ['not_found_error', 404],
+    ['not_found', 404],
+    ['rate_limit_error', 429],
+    ['rate_limit_exceeded', 429],
+    ['resource_exhausted', 429],
+    ['api_error', 500],
+    ['internal', 500],
+    ['unavailable', 503],
+    ['overloaded_error', 529],
+]);
+/** A JSON error body, wherever the message happens to begin with one. */
+function body(text) {
+    const start = text.indexOf('{');
+    if (start === -1) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(start));
+    }
+    catch {
+        // Not JSON, or a body cut short. What is already in hand is the answer.
+        return undefined;
+    }
+    const root = parsed;
+    const error = root?.error ?? root;
+    if (typeof error === 'string') {
+        return { message: error };
+    }
+    if (!error || typeof error !== 'object') {
+        return undefined;
+    }
+    const said = error;
+    if (typeof said.message !== 'string') {
+        return undefined;
+    }
+    return {
+        message: said.message,
+        // `code` is the status on Google and a symbol on OpenAI; `status` is
+        // the other way round. Which is which is decided by the type, not by
+        // the vendor. `type` is where OpenAI and Anthropic keep the kind.
+        status: typeof said.code === 'number' ? said.code : undefined,
+        code: typeof said.status === 'string'
+            ? said.status
+            : typeof said.code === 'string'
+                ? said.code
+                : typeof said.type === 'string'
+                    ? said.type
+                    : undefined,
+        about: aboutOf(said.details) ?? (typeof said.param === 'string' ? said.param : undefined),
+    };
+}
+/** Names of the field a `google.rpc` detail is about, and of what was wrong with it. */
+const VIOLATION = ['field', 'description', 'reason', 'detail', 'message'];
+/**
+ * What a vendor's `details` array says, flattened to one clause.
+ *
+ * This is where a 400 keeps the part a person needs: the top-level message is
+ * `Request contains an invalid argument`, and `fieldViolations[0].field` is the
+ * argument. The shapes are `google.rpc.BadRequest`, `ErrorInfo` and `DebugInfo`
+ * — read by the field names they have in common rather than by `@type`, since
+ * a detail nobody anticipated is still worth printing.
+ */
+function aboutOf(details) {
+    if (!Array.isArray(details)) {
+        return undefined;
+    }
+    const clauses = [];
+    for (const entry of details.flatMap(violations)) {
+        if (!entry || typeof entry !== 'object') {
+            continue;
+        }
+        const said = entry;
+        const parts = VIOLATION.map((key) => said[key]).filter((v) => typeof v === 'string' && v.length > 0);
+        if (parts.length) {
+            clauses.push(parts.join(': '));
+        }
+    }
+    return clauses.length ? clauses.join('; ') : undefined;
+}
+/** A detail entry, or the violations inside it when it carries a list of them. */
+function violations(entry) {
+    const list = entry?.fieldViolations;
+    return Array.isArray(list) ? list : [entry];
+}
+/** One line, however many the vendor sent, and never a whole document. */
+function collapse(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > MAX_DETAIL ? `${flat.slice(0, MAX_DETAIL)}…` : flat;
+}
+/** What an opaque failure blames, from the first cause that says something else. */
+function blamed(err, said) {
+    const seen = new Set();
+    let at = err?.cause;
+    while (at && typeof at === 'object' && !seen.has(at)) {
+        seen.add(at);
+        const link = at;
+        const message = collapse(typeof link.message === 'string' ? link.message : '');
+        if (message && message !== said) {
+            return typeof link.code === 'string' ? `${message} (${link.code})` : message;
+        }
+        at = link.cause;
+    }
+    return undefined;
+}
+/** Appends the status and the vendor's symbol, unless the sentence has them. */
+function mark(text, status, code) {
+    const marks = [];
+    if (status !== undefined && !text.includes(String(status))) {
+        marks.push(String(status));
+    }
+    if (code && !text.toLowerCase().includes(code.toLowerCase())) {
+        marks.push(code);
+    }
+    return marks.length ? `${text} (${marks.join(' ')})` : text;
+}
+//# sourceMappingURL=failure.js.map

package/dist/index.d.ts

@@ -3,11 +3,22 @@ export * from './architecture.ts';
 export * from './embedding.ts';
 export * from './embeddings/index.ts';
 export * from './events.ts';
+export * from './failure.ts';
 export * from './ids.ts';
 export * from './inspect/index.ts';
 export * as Kernel from './kernel.ts';
-export * from './memory-stores/index.ts';
-export * from './memory.ts';
+export * from './memory/files.ts';
+export * from './memory/graph.ts';
+export * from './memory/index.ts';
+export * from './memory/instructions.ts';
+export * from './memory/page.ts';
+export * from './memory/recall.ts';
+export * from './memory/render.ts';
+export * from './memory/report.ts';
+export * from './memory/store.ts';
+export * from './memory/tools.ts';
+export * from './memory/types.ts';
+export * from './memory/vectors.ts';
 export * from './model.ts';
 export * from './models/index.ts';
 export * from './payload-stores/index.ts';

package/dist/index.js

@@ -3,11 +3,22 @@ export * from "./architecture.js";
 export * from "./embedding.js";
 export * from "./embeddings/index.js";
 export * from "./events.js";
+export * from "./failure.js";
 export * from "./ids.js";
 export * from "./inspect/index.js";
 export * as Kernel from "./kernel.js";
-export * from "./memory-stores/index.js";
-export * from "./memory.js";
+export * from "./memory/files.js";
+export * from "./memory/graph.js";
+export * from "./memory/index.js";
+export * from "./memory/instructions.js";
+export * from "./memory/page.js";
+export * from "./memory/recall.js";
+export * from "./memory/render.js";
+export * from "./memory/report.js";
+export * from "./memory/store.js";
+export * from "./memory/tools.js";
+export * from "./memory/types.js";
+export * from "./memory/vectors.js";
 export * from "./model.js";
 export * from "./models/index.js";
 export * from "./payload-stores/index.js";