@7n/tauri-components 0.0.1 → 0.1.1

package/package.json

@@ -1,19 +1,29 @@
 {
   "name": "@7n/tauri-components",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "type": "module",
   "description": "Shared LLM agent engine + Vue/Quasar UI for Tauri apps (chat, journal, trust-tier approval).",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/tauri-components.git",
+    "directory": "npm"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
     "./vue": "./src/vue/index.js",
     "./components": "./src/components/index.js"
   },
   "files": [
     "src",
+    "types",
     "!**/*.test.*",
     "!**/*.spec.*",
     "!**/__tests__/**",

package/types/core/agent-handler.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Start a new agent request.
+ * @param {{ intent: string, actor: object, chat: Function, dispatch: Function, journal: object, tools: object[], gate: Function, buildSystem?: Function, grounding?: object }} opts request parameters
+ * @returns {Promise<object>} structured result envelope
+ */
+export function handleRequest({ intent, actor, chat, dispatch, journal, tools, gate, buildSystem, grounding }: {
+    intent: string;
+    actor: object;
+    chat: Function;
+    dispatch: Function;
+    journal: object;
+    tools: object[];
+    gate: Function;
+    buildSystem?: Function;
+    grounding?: object;
+}): Promise<object>;
+/**
+ * Resume a conversation with a follow-up / clarification answer.
+ * @param {{ requestId: string, message: string, actor: object, chat: Function, dispatch: Function, journal: object, tools: object[], gate: Function }} opts resume parameters
+ * @returns {Promise<object>} updated result envelope
+ */
+export function handleRespond({ requestId, message, chat, dispatch, journal, tools, gate }: {
+    requestId: string;
+    message: string;
+    actor: object;
+    chat: Function;
+    dispatch: Function;
+    journal: object;
+    tools: object[];
+    gate: Function;
+}): Promise<object>;
+/**
+ * Approve (or reject) a pending destructive action. Executes with the approver's
+ * (human) authority via the injected dispatch — no gate.
+ * @param {{ requestId: string, approve: boolean, dispatch: Function, journal: object }} opts approval parameters
+ * @returns {Promise<object>} updated result envelope
+ */
+export function handleApprove({ requestId, approve, dispatch, journal }: {
+    requestId: string;
+    approve: boolean;
+    dispatch: Function;
+    journal: object;
+}): Promise<object>;

package/types/core/agent-kit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @param {object} config kit configuration
+ * @param {object[]} config.catalog tool definitions (required)
+ * @param {string|((ctx: object) => string)} [config.systemPrompt] domain system prompt (or builder from grounding ctx)
+ * @param {(tool: object, input: object) => unknown} [config.transport] backend runner; omit to build the kit without dispatch (manifest/scope only)
+ * @param {object} [config.journal] journal store { create, load, update, list }
+ * @param {Record<string, number>} [config.actorTiers] max executable tier rank per actor kind
+ * @param {{ tool: string, key?: string, fallback?: unknown }} [config.grounding] optional read tool to ground the prompt
+ * @returns {{ dispatch: Function|null, classify: Function, scopedManifest: Function, toolManifest: Function, request: Function, respond: Function, approve: Function }} bound kit
+ */
+export function createAgentKit({ catalog, systemPrompt, transport, journal, actorTiers, grounding }?: {
+    catalog: object[];
+    systemPrompt?: string | ((ctx: object) => string) | undefined;
+    transport?: ((tool: object, input: object) => unknown) | undefined;
+    journal?: object | undefined;
+    actorTiers?: Record<string, number> | undefined;
+    grounding?: {
+        tool: string;
+        key?: string;
+        fallback?: unknown;
+    } | undefined;
+}): {
+    dispatch: Function | null;
+    classify: Function;
+    scopedManifest: Function;
+    toolManifest: Function;
+    request: Function;
+    respond: Function;
+    approve: Function;
+};

package/types/core/dispatch.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate an input object against a tool's schema and custom validator.
+ * @param {object} tool tool definition
+ * @param {object} [input] candidate input
+ * @returns {string|null} error message, or null when valid
+ */
+export function validateInput(tool: object, input?: object): string | null;
+/**
+ * Build a dispatch function bound to a catalog and a transport.
+ * @param {object[]} catalog tool definitions
+ * @param {(tool: object, input: object) => unknown} transport runs the tool's backend call
+ * @returns {(name: string, input?: object) => Promise<object>} dispatch returning an envelope
+ */
+export function createDispatch(catalog: object[], transport: (tool: object, input: object) => unknown): (name: string, input?: object) => Promise<object>;

package/types/core/llm.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Run the tool-calling loop until the model answers without a tool call.
+ * Accepts either a fresh prompt or an existing messages[] for sessional resume.
+ * @param {object} params loop parameters
+ * @param {string} [params.prompt] user request (fresh start)
+ * @param {object[]} [params.messages] existing conversation to resume (takes priority over prompt)
+ * @param {(name: string, input: object) => Promise<object>} params.dispatch tool dispatcher returning an envelope
+ * @param {(req: {messages: object[], tools: object[]}) => Promise<object>} params.chat model call returning an assistant message
+ * @param {number} [params.maxSteps] safety cap on loop iterations
+ * @param {string} [params.system] system prompt (only used when building fresh from prompt)
+ * @param {object[]} [params.tools] LLM tool manifest (pass a scoped manifest to restrict)
+ * @param {(name: string) => 'allow'|'approval'|'deny'} [params.gate] per-call decision (default: allow)
+ * @returns {Promise<{content: string, steps: number, trace: object[], messages: object[], stopped?: string, pendingApproval?: object}>} loop result
+ */
+export function runAgent({ prompt, messages: initialMessages, dispatch, chat, maxSteps, system, tools, gate }: {
+    prompt?: string | undefined;
+    messages?: object[] | undefined;
+    dispatch: (name: string, input: object) => Promise<object>;
+    chat: (req: {
+        messages: object[];
+        tools: object[];
+    }) => Promise<object>;
+    maxSteps?: number | undefined;
+    system?: string | undefined;
+    tools?: object[] | undefined;
+    gate?: ((name: string) => "allow" | "approval" | "deny") | undefined;
+}): Promise<{
+    content: string;
+    steps: number;
+    trace: object[];
+    messages: object[];
+    stopped?: string;
+    pendingApproval?: object;
+}>;
+/**
+ * Build a `chat` function that calls an OpenAI-compatible endpoint (omlx).
+ * @param {object} params config
+ * @param {string} params.baseUrl base URL incl. /v1 (e.g. http://127.0.0.1:10240/v1)
+ * @param {string} params.model served model id
+ * @param {string} [params.apiKey] optional bearer token
+ * @param {typeof fetch} [params.fetchFn] fetch implementation (injectable for tests / tauri-http)
+ * @returns {(req: {messages: object[], tools: object[]}) => Promise<object>} chat function
+ */
+export function createOpenAiChat({ baseUrl, model, apiKey, fetchFn }: {
+    baseUrl: string;
+    model: string;
+    apiKey?: string | undefined;
+    fetchFn?: typeof fetch | undefined;
+}): (req: {
+    messages: object[];
+    tools: object[];
+}) => Promise<object>;

package/types/core/manifest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Convert a tool input spec into a JSON Schema object.
+ * @param {Record<string, {type: string, required?: boolean, description?: string}>} input tool input spec
+ * @returns {object} JSON Schema for the parameters object
+ */
+export function toJsonSchema(input: Record<string, {
+    type: string;
+    required?: boolean;
+    description?: string;
+}>): object;
+/**
+ * OpenAI function-calling tool definitions, optionally filtered (e.g. by scope).
+ * @param {object[]} catalog tool definitions
+ * @param {(tool: object) => boolean} [allow] predicate; default includes all tools
+ * @returns {object[]} OpenAI `tools` array
+ */
+export function toolManifest(catalog: object[], allow?: (tool: object) => boolean): object[];
+/**
+ * Compact catalog listing (name + summary).
+ * @param {object[]} catalog tool definitions
+ * @returns {{name: string, summary: string}[]} tool list
+ */
+export function listTools(catalog: object[]): {
+    name: string;
+    summary: string;
+}[];

package/types/core/scope.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Classify a tool call for an actor.
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @param {string} toolName tool name
+ * @returns {'allow'|'approval'|'deny'} decision
+ */
+export function classify(catalog: object[], actorTiers: Record<string, number> | undefined, actor: {
+    kind?: string;
+}, toolName: string): "allow" | "approval" | "deny";
+/**
+ * LLM tool manifest visible to the actor (everything it may run OR request approval for).
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @returns {object[]} OpenAI tools array
+ */
+export function scopedManifest(catalog: object[], actorTiers: Record<string, number> | undefined, actor: {
+    kind?: string;
+}): object[];
+/**
+ * Tool names visible to the actor.
+ * @param {object[]} catalog tool definitions
+ * @param {Record<string, number>|undefined} actorTiers max executable tier rank per actor kind
+ * @param {{ kind?: string }} actor caller identity
+ * @returns {string[]} visible tool names
+ */
+export function scopedToolNames(catalog: object[], actorTiers: Record<string, number> | undefined, actor: {
+    kind?: string;
+}): string[];
+export namespace DEFAULT_ACTOR_TIERS {
+    let human: number;
+    let agent: number;
+}

package/types/core/tools.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Look up a tool by name in a catalog.
+ * @param {object[]} catalog tool definitions
+ * @param {string} name tool name
+ * @returns {object|null} the tool definition, or null if unknown
+ */
+export function getTool(catalog: object[], name: string): object | null;

package/types/index.d.ts

@@ -0,0 +1,7 @@
+export { createAgentKit } from "./core/agent-kit.js";
+export { getTool } from "./core/tools.js";
+export { handleApprove, handleRequest, handleRespond } from "./core/agent-handler.js";
+export { createDispatch, validateInput } from "./core/dispatch.js";
+export { createOpenAiChat, runAgent } from "./core/llm.js";
+export { listTools, toJsonSchema, toolManifest } from "./core/manifest.js";
+export { classify, DEFAULT_ACTOR_TIERS, scopedManifest, scopedToolNames } from "./core/scope.js";