@chelone/core 0.5.0 → 0.7.0

package/dist/assistant/assistant-session.d.ts

@@ -0,0 +1,28 @@
+import { type MicroStore } from "../store/micro-store.js";
+import type { AssistantMessage, AssistantTool, AssistantToolCall, AssistantTransport } from "./types.js";
+export interface AssistantSessionState {
+    messages: AssistantMessage[];
+    status: "idle" | "streaming" | "error";
+    error: Error | null;
+}
+export interface CreateAssistantSessionOptions {
+    transport: AssistantTransport;
+    tools: Record<string, AssistantTool>;
+    /** Follow-up turns after tool calls before the session gives up. Default 5. */
+    maxToolRounds?: number;
+    /** Answers for tools that set `confirm`. Without it they never run. */
+    confirmTool?: (call: AssistantToolCall) => boolean | Promise<boolean>;
+}
+export interface AssistantSession extends MicroStore<AssistantSessionState> {
+    /** Resolves when the turn, with its tool rounds, ends. */
+    send(text: string): Promise<void>;
+    /**
+     * After an error, runs the last user message again: whatever the failed
+     * turn added after it is dropped and no second user message is added.
+     * Does nothing unless the status is `error`.
+     */
+    retry(): Promise<void>;
+    stop(): void;
+    reset(): void;
+}
+export declare function createAssistantSession({ transport, tools, maxToolRounds, confirmTool, }: CreateAssistantSessionOptions): AssistantSession;

package/dist/assistant/assistant-session.js

@@ -0,0 +1,208 @@
+import { createMicroStore } from "../store/micro-store.js";
+// src/assistant/assistant-session.ts
+var toError = (error) => error instanceof Error ? error : new Error(String(error));
+var issuesText = (issues) => issues.map((issue) => issue.message).join("; ");
+/** Resolves with `undefined` when the signal aborts before the promise settles. */
+function raceAbort(promise, signal) {
+	return new Promise((resolve, reject) => {
+		const onAbort = () => resolve(void 0);
+		if (signal.aborted) return onAbort();
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then(resolve, reject).finally(() => {
+			signal.removeEventListener("abort", onAbort);
+		});
+	});
+}
+function createAssistantSession({ transport, tools, maxToolRounds = 5, confirmTool }) {
+	const store = createMicroStore({
+		messages: [],
+		status: "idle",
+		error: null
+	});
+	const declarations = Object.fromEntries(Object.entries(tools).map(([name, { description, parameters }]) => [name, {
+		description,
+		parameters
+	}]));
+	let active = null;
+	let destroyed = false;
+	store.onDestroy(() => {
+		destroyed = true;
+		active?.abort();
+		active = null;
+	});
+	async function runTool(call, signal) {
+		const base = {
+			role: "tool",
+			id: call.id,
+			toolName: call.toolName
+		};
+		const definition = Object.hasOwn(tools, call.toolName) ? tools[call.toolName] : void 0;
+		if (!definition) return {
+			...base,
+			error: `Unknown tool: ${call.toolName}`
+		};
+		const stopped = {
+			...base,
+			error: "Stopped"
+		};
+		try {
+			let args = call.args;
+			if (definition.schema) {
+				const outcome = await definition.schema["~standard"].validate(args);
+				if (signal.aborted) return stopped;
+				if (outcome.issues) return {
+					...base,
+					error: `Invalid arguments: ${issuesText(outcome.issues)}`
+				};
+				args = outcome.value;
+			}
+			if (definition.confirm) {
+				const answer = await confirmTool?.(call);
+				if (signal.aborted) return stopped;
+				if (!answer) return {
+					...base,
+					error: "The user declined to run this tool"
+				};
+			}
+			return {
+				...base,
+				result: await definition.handler(args)
+			};
+		} catch (error) {
+			return {
+				...base,
+				error: toError(error).message
+			};
+		}
+	}
+	async function run(controller) {
+		const { signal } = controller;
+		const update = (patch) => {
+			if (!signal.aborted) store.setState(patch);
+		};
+		for (let round = 0;; round++) {
+			let content = "";
+			let index = -1;
+			const calls = [];
+			let iterator;
+			try {
+				iterator = transport.send(store.getSnapshot().messages, declarations, { signal })[Symbol.asyncIterator]();
+				for (;;) {
+					const step = await raceAbort(iterator.next(), signal);
+					if (!step || step.done || signal.aborted) break;
+					const chunk = step.value;
+					if (chunk.type === "done") break;
+					if (chunk.type === "tool-call") {
+						const { id, toolName, args } = chunk;
+						calls.push({
+							id,
+							toolName,
+							args
+						});
+						continue;
+					}
+					content += chunk.delta;
+					const text = content;
+					if (index < 0) {
+						index = store.getSnapshot().messages.length;
+						update((s) => ({ messages: [...s.messages, {
+							role: "assistant",
+							content: text
+						}] }));
+					} else update((s) => ({ messages: s.messages.map((m, i) => i === index ? {
+						role: "assistant",
+						content: text
+					} : m) }));
+				}
+			} catch (error) {
+				if (!signal.aborted) update(() => ({
+					status: "error",
+					error: toError(error)
+				}));
+				return;
+			} finally {
+				iterator?.return?.().catch(() => {});
+			}
+			if (signal.aborted) return;
+			if (calls.length === 0) break;
+			if (round >= maxToolRounds) {
+				update(() => ({
+					status: "error",
+					error: /* @__PURE__ */ new Error(`The assistant kept calling tools after ${maxToolRounds} rounds`)
+				}));
+				return;
+			}
+			const results = [];
+			for (const call of calls) {
+				const result = await raceAbort(runTool(call, signal), signal);
+				if (!result) return;
+				results.push(result);
+				if (signal.aborted) return;
+			}
+			const assistant = {
+				role: "assistant",
+				content,
+				toolCalls: calls
+			};
+			update((s) => ({ messages: index < 0 ? [
+				...s.messages,
+				assistant,
+				...results
+			] : [...s.messages.map((m, i) => i === index ? assistant : m), ...results] }));
+		}
+		update(() => ({ status: "idle" }));
+	}
+	async function start(controller) {
+		active = controller;
+		try {
+			await run(controller);
+		} finally {
+			if (active === controller) active = null;
+		}
+	}
+	return {
+		...store,
+		async send(text) {
+			if (destroyed) return;
+			if (!text.trim() || store.getSnapshot().status === "streaming") return;
+			store.setState((s) => ({
+				messages: [...s.messages, {
+					role: "user",
+					content: text
+				}],
+				status: "streaming",
+				error: null
+			}));
+			await start(new AbortController());
+		},
+		async retry() {
+			if (destroyed || store.getSnapshot().status !== "error") return;
+			const { messages } = store.getSnapshot();
+			let last = messages.length - 1;
+			while (last >= 0 && messages[last]?.role !== "user") last--;
+			if (last < 0) return;
+			store.setState({
+				messages: messages.slice(0, last + 1),
+				status: "streaming",
+				error: null
+			});
+			await start(new AbortController());
+		},
+		stop() {
+			if (!active) return;
+			active.abort();
+			active = null;
+			store.setState({ status: "idle" });
+		},
+		reset() {
+			active?.abort();
+			active = null;
+			store.setState({
+				messages: [],
+				status: "idle",
+				error: null
+			});
+		}
+	};
+}
+export { createAssistantSession };

package/dist/assistant/echo-transport.d.ts

@@ -0,0 +1,7 @@
+import type { AssistantTransport } from "./types.js";
+export interface EchoAssistantTransportOptions {
+    /** Waits this long before each character. */
+    delayMs?: number;
+}
+/** Replies `Echo: <last user text>` one character at a time, with no model behind it. */
+export declare function echoAssistantTransport({ delayMs, }?: EchoAssistantTransportOptions): AssistantTransport;

package/dist/assistant/echo-transport.js

@@ -0,0 +1,28 @@
+// src/assistant/echo-transport.ts
+var wait = (ms, signal) => new Promise((resolve) => {
+	const timer = setTimeout(done, ms);
+	function done() {
+		clearTimeout(timer);
+		signal.removeEventListener("abort", done);
+		resolve();
+	}
+	signal.addEventListener("abort", done, { once: true });
+});
+/** Replies `Echo: <last user text>` one character at a time, with no model behind it. */
+function echoAssistantTransport({ delayMs = 0 } = {}) {
+	return { async *send(messages, _tools, { signal }) {
+		let said = "";
+		for (const message of messages) if (message.role === "user") said = message.content;
+		const reply = `Echo: ${said}`;
+		for (const delta of reply) {
+			if (delayMs > 0) await wait(delayMs, signal);
+			if (signal.aborted) return;
+			yield {
+				type: "text",
+				delta
+			};
+		}
+		yield { type: "done" };
+	} };
+}
+export { echoAssistantTransport };

package/dist/assistant/http-transport.d.ts

@@ -0,0 +1,10 @@
+import type { AssistantTransport } from "./types.js";
+export interface HttpAssistantTransportOptions {
+    url: string;
+    /** Resolved for each request so tokens can change between turns. */
+    headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+    credentials?: RequestCredentials;
+    fetch?: typeof globalThis.fetch;
+}
+/** Posts a conversation to an app endpoint that replies with NDJSON AssistantChunks. */
+export declare function httpAssistantTransport(options: HttpAssistantTransportOptions): AssistantTransport;

package/dist/assistant/http-transport.js

@@ -0,0 +1,98 @@
+import { HttpError } from "../data/http-error.js";
+import { isJsonObject, isRecord } from "../guards.js";
+// src/assistant/http-transport.ts
+function parseChunk(line, lineNumber) {
+	const invalid = () => /* @__PURE__ */ new Error(`Invalid assistant chunk at line ${lineNumber}`);
+	let chunk;
+	try {
+		chunk = JSON.parse(line);
+	} catch {
+		throw invalid();
+	}
+	if (isRecord(chunk)) switch (chunk.type) {
+		case "text":
+			if (typeof chunk.delta === "string") return {
+				type: "text",
+				delta: chunk.delta
+			};
+			break;
+		case "tool-call":
+			if (typeof chunk.id === "string" && typeof chunk.toolName === "string" && isJsonObject(chunk.args)) return {
+				type: "tool-call",
+				id: chunk.id,
+				toolName: chunk.toolName,
+				args: chunk.args
+			};
+			break;
+		case "done": return { type: "done" };
+	}
+	throw invalid();
+}
+/** Posts a conversation to an app endpoint that replies with NDJSON AssistantChunks. */
+function httpAssistantTransport(options) {
+	const doFetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	return { async *send(messages, tools, { signal }) {
+		try {
+			if (signal.aborted) return;
+			const headers = new Headers(typeof options.headers === "function" ? await options.headers() : options.headers);
+			if (signal.aborted) return;
+			headers.set("Content-Type", "application/json");
+			const response = await doFetch(options.url, {
+				method: "POST",
+				headers,
+				credentials: options.credentials,
+				body: JSON.stringify({
+					messages,
+					tools
+				}),
+				signal
+			});
+			if (!response.ok) throw new HttpError(`Assistant request failed (HTTP ${response.status})`, response.status, await response.text());
+			const reader = response.body?.getReader();
+			if (reader) {
+				const decoder = new TextDecoder();
+				let pending = "";
+				let lineNumber = 0;
+				let released = false;
+				const release = () => {
+					if (released) return;
+					released = true;
+					reader.cancel().catch(() => {});
+					reader.releaseLock();
+				};
+				signal.addEventListener("abort", release, { once: true });
+				try {
+					for (;;) {
+						if (signal.aborted) return;
+						const step = await reader.read();
+						if (signal.aborted) return;
+						pending += decoder.decode(step.value, { stream: !step.done });
+						if (step.done) pending += "\n";
+						let end = pending.indexOf("\n");
+						while (end >= 0) {
+							if (signal.aborted) return;
+							lineNumber++;
+							const line = pending.slice(0, end).trim();
+							pending = pending.slice(end + 1);
+							if (line) {
+								const chunk = parseChunk(line, lineNumber);
+								yield chunk;
+								if (chunk.type === "done") return;
+							}
+							end = pending.indexOf("\n");
+						}
+						if (step.done) break;
+					}
+				} finally {
+					signal.removeEventListener("abort", release);
+					release();
+				}
+			}
+			if (signal.aborted) return;
+			yield { type: "done" };
+		} catch (error) {
+			if (!signal.aborted) throw error;
+		}
+	} };
+}
+export { httpAssistantTransport };

package/dist/assistant/types.d.ts

@@ -0,0 +1,54 @@
+import type { StandardSchemaV1 } from "@tanstack/form-core";
+import type { JsonObject, JsonValue } from "../guards.js";
+/** A tool call the model asked for. `id` ties the result back to it. */
+export interface AssistantToolCall {
+    id: string;
+    toolName: string;
+    args: JsonObject;
+}
+export type AssistantMessage = {
+    role: "user";
+    content: string;
+} | {
+    role: "assistant";
+    content: string;
+    /** Present once the calls ran and their results follow as tool messages. */
+    toolCalls?: AssistantToolCall[];
+} | {
+    role: "tool";
+    /** The `id` of the call this answers. */
+    id: string;
+    toolName: string;
+    /** What the handler returned; absent when `error` is set. */
+    result?: JsonValue;
+    error?: string;
+};
+export type AssistantChunk = {
+    type: "text";
+    delta: string;
+} | ({
+    type: "tool-call";
+} & AssistantToolCall) | {
+    type: "done";
+};
+export interface AssistantTool {
+    description: string;
+    /** A JSON Schema object, handed to the transport as is. */
+    parameters: JsonObject;
+    /** Method syntax keeps a handler with narrower `args` assignable. */
+    handler(args: JsonObject): JsonValue | undefined | Promise<JsonValue | undefined>;
+    /** Checks the arguments before `handler` runs; its output reaches `handler`. */
+    schema?: StandardSchemaV1<JsonObject, JsonObject>;
+    /** Ask the user through the session's `confirmTool` before this tool runs. */
+    confirm?: boolean;
+}
+/** What a transport learns about a tool: no handler, schema or confirm. */
+export interface AssistantToolDeclaration {
+    description: string;
+    parameters: JsonObject;
+}
+export interface AssistantTransport {
+    send(messages: readonly AssistantMessage[], tools: Readonly<Record<string, AssistantToolDeclaration>>, options: {
+        signal: AbortSignal;
+    }): AsyncIterable<AssistantChunk>;
+}

package/dist/auth/access-control.d.ts

@@ -1,9 +1,17 @@
+import type { ResourceRecord } from "../resource/record.js";
 import type { CanAccessParams } from "./types.js";
-/** One grant. `record` predicate (when present) must pass against a provided record. */
-export interface Permission {
+/**
+ * One grant. `record` predicate (when present) must pass against a provided
+ * record, and reads it as `TRecord` — the same record shape the check is given.
+ */
+export interface Permission<TRecord extends ResourceRecord = ResourceRecord> {
     action: string | string[];
     resource: string;
-    record?: (record: unknown) => boolean;
+    record?: (record: TRecord) => boolean;
 }
-/** Deny-by-default permission matcher (OR across permissions). */
-export declare function canAccessWithPermissions(permissions: Permission[], params: CanAccessParams): boolean;
+/**
+ * Deny-by-default permission matcher (OR across permissions). `TRecord` is fixed
+ * by the permissions and the params together, so a grant's predicate and the
+ * record it reads are the same type.
+ */
+export declare function canAccessWithPermissions<TRecord extends ResourceRecord = ResourceRecord>(permissions: Permission<TRecord>[], params: CanAccessParams<TRecord>): boolean;

package/dist/auth/access-control.js

@@ -1,27 +1,31 @@
+// src/auth/access-control.ts
 function matchesAction(granted, action) {
-  const list = Array.isArray(granted) ? granted : [granted];
-  return list.includes("*") || list.includes(action);
+	const list = Array.isArray(granted) ? granted : [granted];
+	return list.includes("*") || list.includes(action);
 }
 function matchesResource(granted, resource) {
-  if (granted === "*") return true;
-  if (granted.endsWith(".*")) return resource.startsWith(granted.slice(0, -1));
-  return granted === resource;
+	if (granted === "*") return true;
+	if (granted.endsWith(".*")) return resource.startsWith(granted.slice(0, -1));
+	return granted === resource;
 }
+/**
+* Deny-by-default permission matcher (OR across permissions). `TRecord` is fixed
+* by the permissions and the params together, so a grant's predicate and the
+* record it reads are the same type.
+*/
 function canAccessWithPermissions(permissions, params) {
-  return permissions.some((permission) => {
-    if (!matchesAction(permission.action, params.action)) return false;
-    if (!matchesResource(permission.resource, params.resource)) return false;
-    if (permission.record) {
-      if (params.record == null) return false;
-      try {
-        return permission.record(params.record);
-      } catch {
-        return false;
-      }
-    }
-    return true;
-  });
+	return permissions.some((permission) => {
+		if (!matchesAction(permission.action, params.action)) return false;
+		if (!matchesResource(permission.resource, params.resource)) return false;
+		if (permission.record) {
+			if (params.record == null) return false;
+			try {
+				return permission.record(params.record);
+			} catch {
+				return false;
+			}
+		}
+		return true;
+	});
 }
-export {
-  canAccessWithPermissions
-};
+export { canAccessWithPermissions };

package/dist/auth/auth-options.d.ts

@@ -1,19 +1,25 @@
+import { type SkipToken } from "@tanstack/query-core";
 import type { AuthProvider, CanAccessParams, UserIdentity } from "./types.js";
-/** Plain option objects, same convention as the data factories (P2). */
-export declare function identityQueryOptions(authProvider: AuthProvider): {
-    queryKey: readonly ["auth", "getIdentity"];
-    queryFn: () => Promise<UserIdentity>;
-};
-export declare function canAccessQueryOptions(authProvider: AuthProvider, params: CanAccessParams): {
-    queryKey: readonly ["auth", "canAccess", CanAccessParams];
+/** The option shape of the factories that skip with no provider. */
+interface SkippableQueryOptions<TKey, TData> {
+    queryKey: TKey;
+    queryFn: SkipToken | (() => Promise<TData>);
+}
+/** What `getPermissions` takes: the key slot of {@link permissionsQueryOptions}. */
+type PermissionsParams = Parameters<NonNullable<AuthProvider["getPermissions"]>>[0];
+/**
+ * Plain option objects, same convention as the data factories (P2). With no
+ * provider, `identityQueryOptions`, `authStateQueryOptions` and
+ * `permissionsQueryOptions` set `queryFn: skipToken`, so the query never runs.
+ */
+export declare function identityQueryOptions(authProvider: AuthProvider | undefined): SkippableQueryOptions<readonly ["auth", "getIdentity"], UserIdentity>;
+export declare function canAccessQueryOptions(authProvider: AuthProvider | undefined, params: CanAccessParams): {
+    queryKey: readonly ["auth", "canAccess", CanAccessParams<import("../index.js").ResourceRecord<import("../index.js").Identifier>>];
     queryFn: () => Promise<boolean>;
 };
-export declare function authStateQueryOptions(authProvider: AuthProvider): {
-    queryKey: readonly ["auth", "checkAuth"];
-    queryFn: () => Promise<{
-        authenticated: boolean;
-    }>;
-};
+export declare function authStateQueryOptions(authProvider: AuthProvider | undefined): SkippableQueryOptions<readonly ["auth", "checkAuth"], {
+    authenticated: boolean;
+}>;
 /**
  * Fetch the current user permissions via `authProvider.getPermissions`.
  * No `getPermissions` on the provider = permissions not configured =
@@ -22,10 +28,7 @@ export declare function authStateQueryOptions(authProvider: AuthProvider): {
  * a queryFn resolving `undefined`. Mirrors {@link canAccessQueryOptions}: keyed
  * by the passed `params` so distinct param objects cache independently.
  */
-export declare function permissionsQueryOptions(authProvider: AuthProvider, params?: unknown): {
-    queryKey: readonly ["auth", "getPermissions", unknown];
-    queryFn: () => Promise<unknown>;
-};
+export declare function permissionsQueryOptions<TPermissions>(authProvider: AuthProvider<TPermissions> | undefined, params?: unknown): SkippableQueryOptions<readonly ["auth", "getPermissions", PermissionsParams], TPermissions | null>;
 /**
  * The triage result of {@link checkError}. Vanilla (react/vue-free) so both
  * adapters share the reject-payload parsing before doing logout/notify/redirect.
@@ -55,3 +58,4 @@ export interface CheckErrorOutcome {
  *   redirect; only an auth rejection ever logs the user out.
  */
 export declare function checkError(authProvider: AuthProvider, error: unknown): Promise<CheckErrorOutcome>;
+export {};