@jini-ai/core 0.1.0

package/dist/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAkBA,MAAM,UAAU,KAAK,CAAsC,EAAM,EAAE,OAA6B,EAAE;IAChG,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,EAAM,EACN,OAA6B,EAAE;IAE/B,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACjE,CAAC"}

package/dist/tool-registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `ToolRegistry` — the registration half of the tool-execution boundary
+ * (extraction-plan.md §2.5 / §8 task 6). Tools are registered as
+ * `{descriptor, handler, policy}` triples; the registry's *public* surface
+ * (this file's `ToolRegistry` interface, and everything re-exported from
+ * this package's root `index.ts`) exposes only `ToolDescriptor`s —
+ * `register`/`has`/`list`. It never exposes a way to retrieve a `handler`
+ * or `policy` back out.
+ *
+ * That's the load-bearing invariant this task is named after: "handlers
+ * never publicly retrievable (routes/agents can't bypass authz)." A route
+ * or an agent holding a `ToolRegistry` reference can enumerate what's
+ * available and check membership, but the only way to actually *run* a
+ * tool is through `@jini-ai/daemon`'s `ToolExecutor`, which is the sole
+ * consumer of {@link getToolRegistration} — a function deliberately
+ * exported from `./internal.js` (a package-internal entry point, see this
+ * package's `package.json` `exports` map and `source-map.md`) rather than
+ * from the public `index.ts` barrel. Every other caller of
+ * `@jini-ai/core`'s default entry point gets descriptors only.
+ */
+import type { Principal } from './principal.js';
+/** A structural run reference — anything with a stable `id` satisfies this (e.g. `@jini-ai/protocol`'s `RunStatus`). No import needed to satisfy it; see the module doc. */
+export interface RunRef {
+    readonly id: string;
+}
+/**
+ * The public, non-secret shape of a registered tool. Never carries the
+ * handler or policy — those are only reachable via {@link getToolRegistration}.
+ */
+export interface ToolDescriptor {
+    readonly id: string;
+    readonly description?: string;
+    /**
+     * JSON-Schema-shaped description of this tool's accepted input, carried as `unknown` because the
+     * kernel neither parses nor validates it — a schema dialect is a consumer concern, and taking a
+     * validator dependency here would put one in every package that touches a registry.
+     *
+     * It exists because *every* discovery mechanism needs it and nothing else in the kernel can
+     * supply it: a caller that can enumerate `ToolRegistry.list()` still cannot tell an agent what
+     * arguments a tool takes, which reduces discovery to guess-and-check against an opaque id.
+     * Optional and additive, so no existing registration changes shape.
+     */
+    readonly inputSchema?: unknown;
+    /** When true, `ToolExecutor` asks the transport's `ExecutionDelegate.onConfirm` before running, in addition to authorization. */
+    readonly requiresConfirmation?: boolean;
+    /** Milliseconds before `ToolExecutor` aborts an in-flight call and reports `'timed-out'`. Omit for no timeout. */
+    readonly timeoutMs?: number;
+    /** Byte/character ceiling `ToolExecutor` truncates string output to. Omit for no truncation. */
+    readonly maxOutputBytes?: number;
+}
+/** What a `ToolHandler` receives — everything it needs and nothing it could use to bypass the gate (no registry access, no other tools' state). */
+export interface ToolExecutionContext {
+    /** The id `ToolExecutor` assigned this call — for the handler's own logging/correlation; carries no authority (the gate already ran before the handler is invoked). */
+    readonly executionId: string;
+    readonly principal: Principal;
+    readonly run: RunRef;
+    readonly input: unknown;
+    readonly signal: AbortSignal;
+}
+/** Runs the tool's actual side effect. Only ever invoked by `ToolExecutor`, never called directly by a route/agent holding the registry. */
+export type ToolHandler = (ctx: ToolExecutionContext) => Promise<unknown>;
+export type AuthorizationDecision = 'allow' | 'deny';
+export interface ToolAuthorizationContext {
+    readonly principal: Principal;
+    readonly run: RunRef;
+    readonly tool: ToolDescriptor;
+    readonly input: unknown;
+}
+/**
+ * A tool's admission-control rule: given who's calling, on which run, with
+ * what input, is this call allowed at all? Distinct from *confirmation*
+ * (`ToolDescriptor.requiresConfirmation`, a per-call human "are you sure"
+ * gate `ToolExecutor` applies afterward) — a policy answers "is this
+ * principal permitted to use this tool", a confirmation answers "does the
+ * user want to proceed with this specific invocation right now."
+ */
+export interface ToolPolicy {
+    authorize(ctx: ToolAuthorizationContext): AuthorizationDecision | Promise<AuthorizationDecision>;
+}
+export interface ToolRegistration {
+    readonly descriptor: ToolDescriptor;
+    readonly handler: ToolHandler;
+    readonly policy: ToolPolicy;
+}
+/** The public registration/enumeration surface. See the module doc for why `handler`/`policy` never appear here. */
+export interface ToolRegistry {
+    /** @throws If `registration.descriptor.id` is already registered — re-registration must be explicit (unregister is not exposed; this registry is append-only by design, matching the kernel's "tools are registered once at composition time" model). */
+    register(registration: ToolRegistration): void;
+    has(toolId: string): boolean;
+    /** Descriptors only, in registration order. Never the underlying handlers/policies. */
+    list(): readonly ToolDescriptor[];
+}
+/**
+ * Creates an empty, append-only `ToolRegistry`.
+ *
+ * @returns A `ToolRegistry` whose backing `{descriptor, handler, policy}`
+ * map is held in a module-private `WeakMap` keyed by the returned instance
+ * — reachable only via {@link getToolRegistration}, not through any method
+ * on the returned object itself.
+ * @complexity `register`/`has` O(1); `list` O(n) in registered tool count.
+ * @overallScore 100/100
+ */
+export declare function createToolRegistry(): ToolRegistry;
+/**
+ * Package-internal escape hatch: resolves a tool's full `{descriptor,
+ * handler, policy}` registration. Exported only from `./internal.js` (see
+ * this package's `package.json` `exports` map) — `@jini-ai/daemon`'s
+ * `ToolExecutor` is the one and only intended caller. Not re-exported from
+ * `index.ts`, so it never reaches `@jini-ai/core`'s public consumers.
+ *
+ * @internal
+ */
+export declare function getToolRegistration(registry: ToolRegistry, toolId: string): ToolRegistration | undefined;
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,4KAA4K;AAC5K,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,iIAAiI;IACjI,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC,kHAAkH;IAClH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,mJAAmJ;AACnJ,MAAM,WAAW,oBAAoB;IACnC,uKAAuK;IACvK,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,4IAA4I;AAC5I,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE1E,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,GAAG,EAAE,wBAAwB,GAAG,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAClG;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,oHAAoH;AACpH,MAAM,WAAW,YAAY;IAC3B,yPAAyP;IACzP,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC/C,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,uFAAuF;IACvF,IAAI,IAAI,SAAS,cAAc,EAAE,CAAC;CACnC;AAID;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAoBjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAExG"}

package/dist/tool-registry.js

@@ -0,0 +1,43 @@
+const registrationsByRegistry = new WeakMap();
+/**
+ * Creates an empty, append-only `ToolRegistry`.
+ *
+ * @returns A `ToolRegistry` whose backing `{descriptor, handler, policy}`
+ * map is held in a module-private `WeakMap` keyed by the returned instance
+ * — reachable only via {@link getToolRegistration}, not through any method
+ * on the returned object itself.
+ * @complexity `register`/`has` O(1); `list` O(n) in registered tool count.
+ * @overallScore 100/100
+ */
+export function createToolRegistry() {
+    const registrations = new Map();
+    const registry = {
+        register(registration) {
+            if (registrations.has(registration.descriptor.id)) {
+                throw new Error(`ToolRegistry: tool "${registration.descriptor.id}" is already registered`);
+            }
+            registrations.set(registration.descriptor.id, registration);
+        },
+        has(toolId) {
+            return registrations.has(toolId);
+        },
+        list() {
+            return Array.from(registrations.values(), (r) => r.descriptor);
+        },
+    };
+    registrationsByRegistry.set(registry, registrations);
+    return registry;
+}
+/**
+ * Package-internal escape hatch: resolves a tool's full `{descriptor,
+ * handler, policy}` registration. Exported only from `./internal.js` (see
+ * this package's `package.json` `exports` map) — `@jini-ai/daemon`'s
+ * `ToolExecutor` is the one and only intended caller. Not re-exported from
+ * `index.ts`, so it never reaches `@jini-ai/core`'s public consumers.
+ *
+ * @internal
+ */
+export function getToolRegistration(registry, toolId) {
+    return registrationsByRegistry.get(registry)?.get(toolId);
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/tool-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../src/tool-registry.ts"],"names":[],"mappings":"AAsGA,MAAM,uBAAuB,GAAG,IAAI,OAAO,EAA+C,CAAC;AAE3F;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,aAAa,GAAG,IAAI,GAAG,EAA4B,CAAC;IAE1D,MAAM,QAAQ,GAAiB;QAC7B,QAAQ,CAAC,YAA8B;YACrC,IAAI,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;gBAClD,MAAM,IAAI,KAAK,CAAC,uBAAuB,YAAY,CAAC,UAAU,CAAC,EAAE,yBAAyB,CAAC,CAAC;YAC9F,CAAC;YACD,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC;QACD,GAAG,CAAC,MAAc;YAChB,OAAO,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,IAAI;YACF,OAAO,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;QACjE,CAAC;KACF,CAAC;IAEF,uBAAuB,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAsB,EAAE,MAAc;IACxE,OAAO,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;AAC5D,CAAC"}

package/dist/tool-tokens.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRegistry } from './tool-registry.js';
+export declare const ToolRegistryToken: import("./token.js").Token<ToolRegistry, string>;
+//# sourceMappingURL=tool-tokens.d.ts.map

package/dist/tool-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-tokens.d.ts","sourceRoot":"","sources":["../src/tool-tokens.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,eAAO,MAAM,iBAAiB,kDAA2C,CAAC"}

package/dist/tool-tokens.js

@@ -0,0 +1,10 @@
+/**
+ * `@jini-ai/core` DI token for `ToolRegistry` — defined alongside the service
+ * it names, per this package's own composition contract (`token.ts`) and
+ * mirroring `@jini-ai/daemon/src/tokens.ts`'s identical rationale for
+ * `RunLifecycle`/`EventLog`: a kernel-service token lives in the package
+ * that owns the service, not in a central registry.
+ */
+import { token } from './token.js';
+export const ToolRegistryToken = token('jini.toolRegistry');
+//# sourceMappingURL=tool-tokens.js.map

package/dist/tool-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-tokens.js","sourceRoot":"","sources":["../src/tool-tokens.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAe,mBAAmB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@jini-ai/core",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AINSEP/Jini.git",
+    "directory": "packages/core"
+  },
+  "jini": {
+    "domain": "engine",
+    "kind": "kernel",
+    "runtime": "universal",
+    "admission": "locked"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map",
+    "!dist/**/__tests__/**"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}