@jini-ai/core 0.3.0 → 0.4.0

package/dist/pack.d.ts

@@ -26,8 +26,12 @@ import type { AnyToken, ManyToken, Token } from './token.js';
  * silently falling through to a global container.
  */
 export interface PackContainer {
-    get<T>(t: Token<T, string>): T;
-    getMany<T>(t: ManyToken<T, string>): T[];
+    get<T>(required: {
+        token: Token<T, string>;
+    }): T;
+    getMany<T>(required: {
+        token: ManyToken<T, string>;
+    }): T[];
 }
 export interface Pack<Deps extends readonly AnyToken<unknown, string>[] = readonly AnyToken<unknown, string>[], Services = unknown, Name extends string = string> {
     readonly name: Name;
@@ -35,30 +39,54 @@ export interface Pack<Deps extends readonly AnyToken<unknown, string>[] = readon
     readonly services: (c: PackContainer) => Services;
     /**
      * `{descriptor, handler, policy}` triples this pack contributes to the composition's shared
-     * `ToolRegistry`. Called exactly once per composed pack, before any transport is mounted, so a
-     * pack's routes can assume its own tools are already registered.
+     * `ToolRegistry`. Composition roots must call `registerPackTools` exactly once per composed pack,
+     * before mounting any transport, so a pack's routes can assume its tools are already registered.
+     * This interface and `createDaemon` do not enforce that orchestration; repeated registration
+     * invokes the contribution again and duplicate tool IDs are rejected by the registry.
      *
      * Atomic with `http`/`cli` by construction: a pack that is not composed contributes neither its
      * tools nor its routes. See this module's own doc for the failure mode that makes this
      * load-bearing rather than a convenience.
      */
-    readonly tools?: (services: Services) => readonly ToolRegistration[];
-    readonly http?: (app: unknown, services: Services) => void;
-    readonly cli?: (reg: unknown, services: Services) => void;
+    readonly tools?: (required: {
+        services: Services;
+    }) => readonly ToolRegistration[];
+    readonly http?: (required: {
+        app: unknown;
+        services: Services;
+    }) => void;
+    readonly cli?: (required: {
+        reg: unknown;
+        services: Services;
+    }) => void;
     /**
      * Releases whatever this pack's `services` acquired (a pty manager, a database handle, an OAuth
      * callback listener). Composition roots call these in reverse composition order, best-effort:
      * one pack's failure to dispose must never prevent another's from running.
      */
-    readonly dispose?: (services: Services) => Promise<void> | void;
+    readonly dispose?: (required: {
+        services: Services;
+    }) => Promise<void> | void;
+}
+export interface PackContributions<Services> {
+    tools?: (required: {
+        services: Services;
+    }) => readonly ToolRegistration[];
+    http?: (required: {
+        app: unknown;
+        services: Services;
+    }) => void;
+    cli?: (required: {
+        reg: unknown;
+        services: Services;
+    }) => void;
+    dispose?: (required: {
+        services: Services;
+    }) => Promise<void> | void;
 }
 export declare function definePack<const Name extends string, const Deps extends readonly AnyToken<unknown, string>[], Services>(def: {
     name: Name;
     deps: Deps;
     services: (c: PackContainer) => Services;
-    tools?: (services: Services) => readonly ToolRegistration[];
-    http?: (app: unknown, services: Services) => void;
-    cli?: (reg: unknown, services: Services) => void;
-    dispose?: (services: Services) => Promise<void> | void;
-}): Pack<Deps, Services, Name>;
+}, optional?: PackContributions<Services>): Pack<Deps, Services, Name>;
 //# sourceMappingURL=pack.d.ts.map

package/dist/pack.js

@@ -1,4 +1,4 @@
-export function definePack(def) {
-    return def;
+export function definePack(def, optional = {}) {
+    return { ...def, ...optional };
 }
 //# sourceMappingURL=pack.js.map

package/dist/primitives/http.d.ts

@@ -0,0 +1,57 @@
+/** One shared contract keeps binary, mail and webhook consumers behind the same egress guard.
+ * A guarded request requires a socket idle budget; total elapsed time is opt-in. */
+export type HttpRequest = {
+    /** HEAD supports certificate/header diagnostics without downloading the page body. */
+    method: "POST" | "GET" | "HEAD" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers: Readonly<Record<string, string>>;
+    /** Preserve the signed bytes: re-serialization between signing and sending changes the signature. */
+    body?: string;
+    /** Whole-operation deadline, including DNS, redirects and body reads. Off by default.
+     * Retry/backoff belongs to the caller; its deadline can cover the whole retry operation. */
+    totalDeadlineMs?: number;
+    /** Bound the whole operation, including DNS and body reads, beyond the per-attempt timeout. */
+    signal?: AbortSignal;
+    /** Caller byte ceilings are bounded by the client policy, never a way to widen its cap. */
+    maxResponseBytes?: number;
+} & ({
+    idleTimeoutMs: number; /** Legacy alias for the socket idle budget. */
+    timeoutMs?: number;
+} | {
+    timeoutMs: number;
+    idleTimeoutMs?: number;
+});
+export interface HttpResponse {
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    /** Bounded by the egress cap: a producer must not expose an unlimited text body through this port. */
+    bodyText: string;
+    /** Keep individual lines: Expires contains commas, so comma-splitting loses cookie boundaries. */
+    setCookies?: readonly string[];
+    /** UTF-8 decoding replaces invalid sequences and corrupts binary payloads. Expose the decompressed
+     * transport bytes here so binary consumers need not bypass DNS checks, peer pinning or redirects.
+     * Optional for older adapters/doubles; absence does not imply an empty payload. */
+    bodyBytes?: Uint8Array;
+    /** Coarse OR of text/byte clipping. A clipped image is corrupt, not merely smaller. Lossy UTF-8
+     * can expand invalid bytes into three-byte replacement characters and clip text even when all
+     * bytes fit, so binary consumers must use bodyBytesTruncated. Absence is an unknown verdict. */
+    bodyTruncated?: boolean;
+    /** Byte-specific completeness. A producer's unshaped truncation must count against both shapes
+     * rather than silently declaring bytes complete. Absent when no byte payload was supplied. */
+    bodyBytesTruncated?: boolean;
+    /** Provenance must name the guarded hop that supplied these bytes, not the requested URL or an
+     * unfollowed Location. Every followed hop is re-vetted. Older producers may omit this field,
+     * in which case consumers fall back to the request URL rather than inventing a blank source. */
+    finalUrl?: string;
+}
+export type RequestRedirect = "follow" | "error" | "manual";
+/** Consumers receive the policy-enforcing client; the raw transport is a composition seam.
+ * Keeping construction at the host boundary prevents consumers from bypassing egress checks. */
+export interface HttpClientPort {
+    send(required: {
+        request: HttpRequest;
+    }, optional?: {
+        redirect?: RequestRedirect;
+    }): Promise<HttpResponse>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/primitives/http.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http.js.map

package/dist/primitives/ids.d.ts

@@ -0,0 +1,8 @@
+/** Unbranded identifier; UUID-producing adapters and opaque host IDs share this port. */
+export type UUID = string;
+export interface IdGenerator {
+    newId(): string;
+}
+/** Uses the host's cryptographic UUID generator; no insecure random fallback. */
+export declare function createRandomUuidGenerator(): IdGenerator;
+//# sourceMappingURL=ids.d.ts.map

package/dist/primitives/ids.js

@@ -0,0 +1,5 @@
+/** Uses the host's cryptographic UUID generator; no insecure random fallback. */
+export function createRandomUuidGenerator() {
+    return { newId: () => globalThis.crypto.randomUUID() };
+}
+//# sourceMappingURL=ids.js.map

package/dist/primitives/index.d.ts

@@ -0,0 +1,8 @@
+export * from './time.js';
+export * from './ids.js';
+export * from './json.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './result.js';
+export * from './paths.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -0,0 +1,8 @@
+export * from './time.js';
+export * from './ids.js';
+export * from './json.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './result.js';
+export * from './paths.js';
+//# sourceMappingURL=index.js.map

package/dist/primitives/json.d.ts

@@ -0,0 +1,10 @@
+/** JSON wire values shared by contracts and domain packages. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type JsonArray = JsonValue[];
+//# sourceMappingURL=json.d.ts.map

package/dist/primitives/json.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=json.js.map

package/dist/primitives/logger.d.ts

@@ -0,0 +1,26 @@
+/** Host-independent logging contract: diagnostics travel as optional structured data. */
+export interface Logger {
+    info(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+    warn(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+    error(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+}
+/** Minimal console adapter with a required host-owned prefix and structured metadata. */
+export declare function createConsoleLogger({ prefix }: {
+    prefix: string;
+}): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/primitives/logger.js

@@ -0,0 +1,17 @@
+/** Minimal console adapter with a required host-owned prefix and structured metadata. */
+export function createConsoleLogger({ prefix }) {
+    const write = (level, message, optional) => {
+        const args = [prefix ? `${prefix} ${message}` : message];
+        if (optional.meta !== undefined)
+            args.push(optional.meta);
+        if (optional.error !== undefined)
+            args.push(optional.error);
+        console[level](...args);
+    };
+    return {
+        info: ({ message }, optional = {}) => write('info', message, optional),
+        warn: ({ message }, optional = {}) => write('warn', message, optional),
+        error: ({ message }, optional = {}) => write('error', message, optional),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/primitives/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check lexical containment using whole directory segments, including equality.
+ * Hosts resolve cwd-relative paths and symlinks before calling: checking a textual
+ * prefix alone can permit traversal or a symlink escape. Keeping that effect outside
+ * this helper makes the kernel browser-safe. Windows hosts select case-insensitive
+ * comparison and backslash separators; drive roots and UNC share roots remain distinct.
+ * POSIX backslashes remain literal characters, so distinct directories cannot alias.
+ */
+export declare function pathContains({ root, target }: {
+    root: string;
+    target: string;
+}, { caseSensitive, separator }?: {
+    caseSensitive?: boolean;
+    separator?: '/' | '\\';
+}): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/primitives/paths.js

@@ -0,0 +1,38 @@
+/** Pure lexical normalization of an already absolute path; no cwd, filesystem or symlink access. */
+function normalizeAbsolutePath(value, separator) {
+    const path = separator === '\\' ? value.replace(/\\/g, '/') : value;
+    const drive = separator === '\\' ? /^[A-Za-z]:\//.exec(path)?.[0] : undefined;
+    const unc = separator === '\\' ? /^\/\/[^/]+\/[^/]+(?:\/|$)/.exec(path)?.[0] : undefined;
+    const prefix = drive ?? unc ?? (path.startsWith('/') ? '/' : undefined);
+    if (!prefix)
+        throw new RangeError('pathContains requires resolved absolute paths');
+    const segments = [];
+    for (const segment of path.slice(prefix.length).split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..')
+            segments.pop();
+        else
+            segments.push(segment);
+    }
+    return prefix.replace(/\/+$/, '') + '/' + segments.join('/');
+}
+/**
+ * Check lexical containment using whole directory segments, including equality.
+ * Hosts resolve cwd-relative paths and symlinks before calling: checking a textual
+ * prefix alone can permit traversal or a symlink escape. Keeping that effect outside
+ * this helper makes the kernel browser-safe. Windows hosts select case-insensitive
+ * comparison and backslash separators; drive roots and UNC share roots remain distinct.
+ * POSIX backslashes remain literal characters, so distinct directories cannot alias.
+ */
+export function pathContains({ root, target }, { caseSensitive = true, separator = '/' } = {}) {
+    const normalize = (value) => {
+        const path = normalizeAbsolutePath(value, separator);
+        return caseSensitive ? path : path.toLowerCase();
+    };
+    const normalizedRoot = normalize(root);
+    const normalizedTarget = normalize(target);
+    const boundary = normalizedRoot.endsWith('/') ? normalizedRoot : normalizedRoot + '/';
+    return normalizedTarget === normalizedRoot || normalizedTarget.startsWith(boundary);
+}
+//# sourceMappingURL=paths.js.map

package/dist/primitives/result.d.ts

@@ -0,0 +1,9 @@
+/** Explicit success/failure result without exceptions or domain-specific error assumptions. */
+export type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+//# sourceMappingURL=result.d.ts.map

package/dist/primitives/result.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=result.js.map

package/dist/primitives/time.d.ts

@@ -0,0 +1,17 @@
+/** Unbranded wire timestamp: hosts can share clocks without conversion adapters. */
+export type ISODateTime = string;
+/** Milliseconds since the Unix epoch. Zero-argument getters need no empty argument object. */
+export interface Clock {
+    nowMs(): number;
+}
+/** Default wall clock; inject a Clock to control time in application code. */
+export declare function createSystemClock(): Clock;
+/** Converts epoch milliseconds using the standard UTC ISO representation. Invalid time throws. */
+export declare function toIsoDateTime({ epochMs }: {
+    epochMs: number;
+}): ISODateTime;
+/** Samples the supplied clock once and formats its time in UTC. */
+export declare function nowIso({ clock }: {
+    clock: Clock;
+}): ISODateTime;
+//# sourceMappingURL=time.d.ts.map

package/dist/primitives/time.js

@@ -0,0 +1,13 @@
+/** Default wall clock; inject a Clock to control time in application code. */
+export function createSystemClock() {
+    return { nowMs: () => Date.now() };
+}
+/** Converts epoch milliseconds using the standard UTC ISO representation. Invalid time throws. */
+export function toIsoDateTime({ epochMs }) {
+    return new Date(epochMs).toISOString();
+}
+/** Samples the supplied clock once and formats its time in UTC. */
+export function nowIso({ clock }) {
+    return toIsoDateTime({ epochMs: clock.nowMs() });
+}
+//# sourceMappingURL=time.js.map

package/dist/redact.d.ts

@@ -1,19 +1,23 @@
 /**
  * @module redact
  *
- * Lexical secret / PII scrubber for telemetry payloads. Verbatim port of
- * OD's `apps/daemon/src/redact.ts` — no product-identity strings or
- * hardcoded env vars in the original, so no genericization was needed.
+ * Lexical secret / PII scrubber for telemetry payloads. Originally a verbatim port of
+ * OD's daemon redactor — no product-identity strings or hardcoded env vars in the original,
+ * so no genericization was needed. The shared kernel now also covers the CLI/provider rule
+ * union and accepts explicit host secrets; the original categories and rationale stay here.
  *
  * Runs before any prompt or assistant text is sent to an external
- * observability sink. The patterns here are intentionally conservative:
+ * observability sink. The default policy is intentionally conservative:
  * each one matches a well-defined token shape with extremely low
  * false-positive rate (API keys have a fixed prefix, JWTs have the
  * "header.payload.signature" triple, credit-card matches go through a Luhn
  * check). What this file does NOT do — and any caller-facing copy must
  * reflect that — is detect names, addresses, business secrets, or anything
  * that requires understanding the meaning of the surrounding text. That's
- * an ML / LLM problem this module doesn't take on.
+ * an ML / LLM problem this module doesn't take on. Callers can explicitly opt
+ * into `policy: 'aggressive'` to also mask bare 20+ character opaque runs;
+ * that CLI-style heuristic trades identifier/path readability for broader masking
+ * and must never be used by diagnostics or secret-scan guards.
  *
  * Output format: every match is replaced by `[REDACTED:<kind>]` so a
  * reviewer reading a trace can see exactly which category fired without
@@ -27,21 +31,52 @@
  * - AWS access key shape: 'AKIA' + 16 uppercase alphanumerics.
  * - Luhn algorithm (credit cards): https://en.wikipedia.org/wiki/Luhn_algorithm
  */
+/** Credential-shape vocabulary for secret-only redaction; no I/O or host dependencies. */
+export interface SecretShapePattern {
+    readonly name: string;
+    readonly pattern: RegExp;
+}
+export declare const PEM_PATTERN_NAME = "PEM private key block";
+export declare const SECRET_SHAPE_PATTERNS: readonly SecretShapePattern[];
+export interface SecretRedactionPattern {
+    name: string;
+    regex: RegExp;
+}
+/** Optional caller-owned secrets and named lexical rules, without ambient credential lookup. */
+export interface SecretRedactionOptions {
+    /** Conservative by default; aggressive also masks bare 20+ character opaque runs. */
+    policy?: 'conservative' | 'aggressive';
+    exactSecrets?: ReadonlyArray<string | undefined | null>;
+    extraPatterns?: readonly SecretRedactionPattern[];
+}
+export declare const LABELED_SECRET_RE: RegExp;
+export declare const OPAQUE_TOKEN_RE: RegExp;
+export declare const NON_SECRET_TOKEN_RE: RegExp;
 /**
  * Returns `input` with every recognised secret / PII pattern replaced by a
  * `[REDACTED:<kind>]` marker. Idempotent — re-running on already redacted
- * text only matches new tokens.
+ * text only matches new tokens. Defaults to conservative; `{ policy: 'aggressive' }`
+ * additionally masks bare 20+ character opaque runs. Exact secrets and extra patterns
+ * are honored under either policy.
  *
  * Empty / non-string input passes through unchanged so the caller can use
  * this as a no-op on optional fields.
  */
-export declare function redactSecrets(input: string): string;
+export declare function redactSecrets({ input }: {
+    input: string;
+}, options?: SecretRedactionOptions): string;
 /**
  * Same as {@link redactSecrets} but also returns per-category counts so the
  * caller can attach an audit summary to the trace metadata ('we stripped 2
  * keys + 1 email before send').
+ *
+ * Exact secrets run first, longest first: lexical rules or a shorter supplied secret must not
+ * split a known credential and leave a suffix behind. Opt-in aggressive opaque rules precede
+ * PII rules for the same reason (a numeric token can also contain phone/card candidates).
  */
-export declare function redactSecretsWithCounts(input: string): {
+export declare function redactSecretsWithCounts({ input }: {
+    input: string;
+}, options?: SecretRedactionOptions): {
     redacted: string;
     counts: Record<string, number>;
 };