@jini-ai/agentic 0.1.0

package/dist/capability.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module capability
+ *
+ * The vocabulary every agent-drivable surface shares: what an outside caller may ask a
+ * frontend to do, described as pure data with no transport, DOM, or framework attached.
+ *
+ * One noun, deliberately: **capability**. The chat pane's first draft used `tool` in its
+ * type names and `capability` in its ids, which forked the vocabulary across four files.
+ * `tool` stays reserved for the engine's own `ToolRegistry`/`ToolExecutor` nouns; anything
+ * an outside caller asks a *frontend* to do is a capability. Transports may of course
+ * present capabilities as MCP tools — that is a projection, not a rename.
+ */
+/** How much damage a capability can do. `requiresConfirmation` is the enforcement; this is the label. */
+export type CapabilityRisk = 'read' | 'write';
+/**
+ * Whether a capability means anything without a live UI session attached.
+ *
+ * - `session` — needs a connected frontend. "Highlight this field" is meaningless with no
+ *   tab open, and must fail closed with a distinct error rather than hanging on a timeout.
+ * - `server` — a product outcome the backend can satisfy headlessly. Sending a chat message
+ *   is the same outcome whether a tab is open or not.
+ *
+ * This decides *availability*, so a caller can be told "no eligible frontend is connected"
+ * instead of waiting for a timeout that will never resolve.
+ */
+export type CapabilitySurface = 'session' | 'server';
+export interface CapabilityInputSchema {
+    readonly type: 'object';
+    readonly properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: readonly string[];
+    }>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: boolean;
+}
+export interface CapabilityDef {
+    readonly id: string;
+    readonly description: string;
+    readonly inputSchema: CapabilityInputSchema;
+    readonly risk: CapabilityRisk;
+    readonly surface: CapabilitySurface;
+    /**
+     * Destructive or otherwise irreversible — the caller must acknowledge before it runs. A host
+     * with a real confirmation gate (`@jini-ai/daemon`'s `ToolExecutor` has a resumable one) should
+     * enforce it there; surfaces without one enforce it in-band by requiring `confirm: true`, so
+     * no transport can execute it by accident.
+     */
+    readonly requiresConfirmation?: boolean;
+}
+/**
+ * Looks a capability up by id.
+ *
+ * @param capabilities - The manifest to search.
+ * @param id - Capability id to resolve.
+ * @returns The definition, or `undefined` when the id is not in the manifest.
+ */
+export declare function findCapability(capabilities: readonly CapabilityDef[], id: string): CapabilityDef | undefined;
+/**
+ * Checks caller input against a capability's declared schema.
+ *
+ * Manifests advertise `additionalProperties: false` and a `required` list, but nothing was
+ * enforcing either — handlers read the fields they knew about and ignored the rest, so a
+ * misnamed argument silently became a missing one. This closes that for any surface that calls
+ * it. Intentionally a shallow check, not a JSON Schema engine: these schemas are flat by
+ * construction, and a real validator is a dependency this package will not take.
+ *
+ * @param capability - The capability being invoked.
+ * @param input - Raw caller-supplied arguments.
+ * @returns An error message, or `null` when the input is acceptable.
+ */
+export declare function findCapabilityInputError(capability: CapabilityDef, input: Record<string, unknown>): string | null;
+/**
+ * The capabilities a caller may use given what is currently connected.
+ *
+ * @param capabilities - The full manifest.
+ * @param hasSession - Whether a live frontend session is attached.
+ * @returns Only the capabilities that can actually be satisfied right now.
+ */
+export declare function availableCapabilities(capabilities: readonly CapabilityDef[], hasSession: boolean): readonly CapabilityDef[];
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yGAAyG;AACzG,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,qBAAqB,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,aAAa,EAAE,EACtC,EAAE,EAAE,MAAM,GACT,aAAa,GAAG,SAAS,CAE3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,aAAa,EACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,GAAG,IAAI,CAiCf;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,SAAS,aAAa,EAAE,EACtC,UAAU,EAAE,OAAO,GAClB,SAAS,aAAa,EAAE,CAE1B"}

package/dist/capability.js

@@ -0,0 +1,79 @@
+/**
+ * @module capability
+ *
+ * The vocabulary every agent-drivable surface shares: what an outside caller may ask a
+ * frontend to do, described as pure data with no transport, DOM, or framework attached.
+ *
+ * One noun, deliberately: **capability**. The chat pane's first draft used `tool` in its
+ * type names and `capability` in its ids, which forked the vocabulary across four files.
+ * `tool` stays reserved for the engine's own `ToolRegistry`/`ToolExecutor` nouns; anything
+ * an outside caller asks a *frontend* to do is a capability. Transports may of course
+ * present capabilities as MCP tools — that is a projection, not a rename.
+ */
+/**
+ * Looks a capability up by id.
+ *
+ * @param capabilities - The manifest to search.
+ * @param id - Capability id to resolve.
+ * @returns The definition, or `undefined` when the id is not in the manifest.
+ */
+export function findCapability(capabilities, id) {
+    return capabilities.find((capability) => capability.id === id);
+}
+/**
+ * Checks caller input against a capability's declared schema.
+ *
+ * Manifests advertise `additionalProperties: false` and a `required` list, but nothing was
+ * enforcing either — handlers read the fields they knew about and ignored the rest, so a
+ * misnamed argument silently became a missing one. This closes that for any surface that calls
+ * it. Intentionally a shallow check, not a JSON Schema engine: these schemas are flat by
+ * construction, and a real validator is a dependency this package will not take.
+ *
+ * @param capability - The capability being invoked.
+ * @param input - Raw caller-supplied arguments.
+ * @returns An error message, or `null` when the input is acceptable.
+ */
+export function findCapabilityInputError(capability, input) {
+    const { properties, required, additionalProperties } = capability.inputSchema;
+    for (const name of required ?? []) {
+        if (input[name] === undefined)
+            return `"${name}" is required`;
+    }
+    if (additionalProperties === false) {
+        // `key in properties` walks the whole prototype chain, so a key that happens to be inherited
+        // from Object.prototype (`__proto__`, `constructor`, `toString`, `valueOf`, …) reads as
+        // "known" regardless of whether the schema actually lists it — `'constructor' in {}` is
+        // true even on an empty object. `JSON.parse('{"__proto__":...}')` creates a real own data
+        // property (not the accessor), so this was a live way for such a key to escape the
+        // "unknown argument" refusal entirely. hasOwnProperty ignores the prototype chain, so only
+        // keys the schema actually declares count as known.
+        const unknown = Object.keys(input)
+            .filter((key) => !Object.prototype.hasOwnProperty.call(properties, key));
+        if (unknown.length > 0) {
+            return `unknown ${unknown.length === 1 ? 'argument' : 'arguments'}: ${unknown.sort().join(', ')}`;
+        }
+    }
+    for (const [name, schema] of Object.entries(properties)) {
+        const value = input[name];
+        if (value === undefined)
+            continue;
+        const actual = Array.isArray(value) ? 'array' : typeof value;
+        if (actual !== schema.type)
+            return `"${name}" must be a ${schema.type}, received ${actual}`;
+        if (schema.enum !== undefined && !schema.enum.includes(value)) {
+            return `"${name}" must be one of: ${schema.enum.join(', ')}`;
+        }
+    }
+    return null;
+}
+/**
+ * The capabilities a caller may use given what is currently connected.
+ *
+ * @param capabilities - The full manifest.
+ * @param hasSession - Whether a live frontend session is attached.
+ * @returns Only the capabilities that can actually be satisfied right now.
+ */
+export function availableCapabilities(capabilities, hasSession) {
+    return hasSession ? capabilities : capabilities.filter((c) => c.surface === 'server');
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwCH;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAsC,EACtC,EAAU;IAEV,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAAyB,EACzB,KAA8B;IAE9B,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,oBAAoB,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;IAE9E,KAAK,MAAM,IAAI,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QAClC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,IAAI,eAAe,CAAC;IAChE,CAAC;IAED,IAAI,oBAAoB,KAAK,KAAK,EAAE,CAAC;QACnC,6FAA6F;QAC7F,wFAAwF;QACxF,wFAAwF;QACxF,0FAA0F;QAC1F,mFAAmF;QACnF,2FAA2F;QAC3F,oDAAoD;QACpD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;aAC/B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,WAAW,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpG,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;QAC7D,IAAI,MAAM,KAAK,MAAM,CAAC,IAAI;YAAE,OAAO,IAAI,IAAI,eAAe,MAAM,CAAC,IAAI,cAAc,MAAM,EAAE,CAAC;QAC5F,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;YACxE,OAAO,IAAI,IAAI,qBAAqB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/D,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,YAAsC,EACtC,UAAmB;IAEnB,OAAO,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC;AACxF,CAAC"}

package/dist/dom/dom-page-driver.d.ts

@@ -0,0 +1,29 @@
+import type { PageDriver } from '../page-driver.js';
+export interface DomPageDriverOptions {
+    /** The subtree to expose. Never pass `document`. */
+    readonly root: ParentNode & {
+        querySelector: Element['querySelector'];
+    };
+    /** Page ids this driver may navigate to, and how to get there. */
+    readonly pages: Readonly<Record<string, () => void>>;
+    /**
+     * The id of the page currently shown, reported on every element.
+     *
+     * Omit it in a single-page app that swaps views: the driver then reads `data-agent-page` from
+     * the live DOM on every call, so navigating actually changes what elements report. A value
+     * captured here is fixed for the driver's whole lifetime, which is right only for a surface that
+     * never changes view — and silently wrong for one that does, since the driver outlives any one
+     * view (it is bound to the connection, not the render).
+     */
+    readonly currentPage?: string | undefined;
+}
+/**
+ * Builds a driver over `root`.
+ *
+ * @param options - The subtree, the navigable pages, and the current page id.
+ * @returns A driver ready to hand to `executePageCapability`.
+ */
+export declare function createDomPageDriver(options: DomPageDriverOptions): PageDriver;
+/** Reads the current page's `data-agent-page`, for hosts that tag the body. */
+export declare function currentAgentPage(root: ParentNode): string | undefined;
+//# sourceMappingURL=dom-page-driver.d.ts.map

package/dist/dom/dom-page-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-page-driver.d.ts","sourceRoot":"","sources":["../../src/dom/dom-page-driver.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAsB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAoMxE,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG;QAAE,aAAa,EAAE,OAAO,CAAC,eAAe,CAAC,CAAA;KAAE,CAAC;IACxE,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACrD;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,UAAU,CAwT7E;AAgDD,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGrE"}