@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/agent-tools/agent-manifest.js

@@ -0,0 +1,252 @@
+import { hasAccess, isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-framework/engine";
+import { translationValueOtherText } from "@cosmicdrift/kumiko-framework/ui-types";
+import * as z from "zod";
+/** The manifest surfaces one string per locale — a plural entry reads as its
+ *  CLDR `other` form since the manifest has no `count` to select a category. */
+function entryAsLabels(entry) {
+    return Object.fromEntries(Object.entries(entry).map(([locale, value]) => [locale, translationValueOtherText(value)]));
+}
+/** Translation keys carry a feature prefix the manifest can't reconstruct
+ *  (`showcase:entity:item:field:title`), so match on the suffix instead. */
+function labelsForSuffix(translations, suffix) {
+    for (const [key, labels] of Object.entries(translations)) {
+        if (key === suffix || key.endsWith(suffix))
+            return entryAsLabels(labels);
+    }
+    return {};
+}
+/** Nav/screen/workspace gating is opt-in: no rule means visible to everyone
+ *  (NavDefinition.access). Handlers are the opposite — `hasAccess` is
+ *  default-deny there. */
+function uiVisible(access, roles) {
+    return access === undefined || hasAccess({ roles }, access);
+}
+// localeCompare depends on the runtime locale and ICU punctuation rules; qualified
+// names contain `:`, so compare by code point instead for deterministic ordering.
+function compareIds(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function dedupeSorted(values) {
+    return [...new Set(values)].sort(compareIds);
+}
+// Map iteration follows the feature-mount order; the manifest must not depend on it.
+function sortedByKey(items, key) {
+    return [...items].sort((a, b) => compareIds(key(a), key(b)));
+}
+function visibleWorkspaceIds(workspaceIds, workspaces, roles) {
+    if (!workspaceIds)
+        return [];
+    return dedupeSorted(workspaceIds.filter((id) => {
+        const workspace = workspaces.get(id);
+        return workspace !== undefined && uiVisible(workspace.access, roles);
+    }));
+}
+function isFilterableField(field) {
+    return "filterable" in field && field.filterable === true;
+}
+function isPiiField(field) {
+    return "pii" in field && field.pii === true;
+}
+function buildField(entityName, fieldName, field, translations, searchableFields) {
+    const options = field.type === "select" || field.type === "multiSelect" ? field.options : undefined;
+    const references = field.type === "reference" ? field.entity : undefined;
+    return {
+        name: fieldName,
+        type: field.type,
+        labels: labelsForSuffix(translations, `:entity:${entityName}:field:${fieldName}`),
+        ...(field.description !== undefined && { description: field.description }),
+        ...(options !== undefined && { options }),
+        ...(references !== undefined && { references }),
+        ...(searchableFields.has(fieldName) && { searchable: true }),
+        ...(isFilterableField(field) && { filterable: true }),
+        ...(isPiiField(field) && { pii: true }),
+    };
+}
+/** Entity schemas are emitted unfiltered by design: roles gate handlers, screens,
+ *  navs and workspaces, while the handler pipeline gates the values themselves.
+ *  The manifest describes shape, never data. */
+function buildEntities(entities, translations, getSearchableFields) {
+    const result = [];
+    for (const [entityName, entity] of entities) {
+        const searchableFields = new Set(getSearchableFields(entityName));
+        const fields = Object.entries(entity.fields).map(([fieldName, field]) => buildField(entityName, fieldName, field, translations, searchableFields));
+        result.push({
+            name: entityName,
+            labels: labelsForSuffix(translations, `:entity:${entityName}`),
+            ...(entity.description !== undefined && { description: entity.description }),
+            fields,
+        });
+    }
+    return result;
+}
+function buildFeatures(features) {
+    const result = [];
+    for (const [, feature] of features) {
+        result.push({
+            name: feature.name,
+            ...(feature.description !== undefined && { description: feature.description }),
+            ...(feature.uiHints?.displayLabel !== undefined && {
+                displayLabel: feature.uiHints.displayLabel,
+            }),
+        });
+    }
+    return result;
+}
+function buildHandlerEntry(qn, kind, def, roles, getHandlerEntity, denyQns) {
+    if (denyQns.has(qn))
+        return undefined;
+    const exposure = resolveAgentExposure(def, kind);
+    if (!exposure.expose)
+        return undefined;
+    if (!hasAccess({ roles }, def.access))
+        return undefined;
+    // `agent.expose: true` without a `description` still opts in — the author
+    // asked for exposure explicitly, there's just nothing to show as prose.
+    const description = def.description ?? "";
+    let inputSchema;
+    try {
+        // A handler whose schema can't be expressed as JSON Schema (transforms,
+        // z.instanceof, ...) is unusable for an agent tool call — leave it out
+        // rather than ship a broken tool.
+        inputSchema = z.toJSONSchema(def.schema, { io: "input" });
+    }
+    catch {
+        return undefined;
+    }
+    const entity = getHandlerEntity(qn);
+    return {
+        qn,
+        kind,
+        description,
+        risk: exposure.risk,
+        inputSchema,
+        ...(entity !== undefined && { entity }),
+    };
+}
+function buildHandlers(queryHandlers, writeHandlers, roles, getHandlerEntity, denyQns) {
+    const result = [];
+    for (const [qn, def] of queryHandlers) {
+        const entry = buildHandlerEntry(qn, "query", def, roles, getHandlerEntity, denyQns);
+        if (entry)
+            result.push(entry);
+    }
+    for (const [qn, def] of writeHandlers) {
+        const entry = buildHandlerEntry(qn, "write", def, roles, getHandlerEntity, denyQns);
+        if (entry)
+            result.push(entry);
+    }
+    return result;
+}
+function buildNavs(navs, workspaces, translations, roles, screens) {
+    const result = [];
+    for (const [, nav] of navs) {
+        if (!uiVisible(nav.access, roles))
+            continue;
+        // A nav pointing at an opted-out screen would leak its id and label back
+        // into the manifest the screen was just removed from.
+        const target = nav.screen !== undefined ? screens.get(nav.screen) : undefined;
+        if (target !== undefined && !isAgentVisibleScreen(target))
+            continue;
+        const visibleWorkspaces = visibleWorkspaceIds(nav.workspaces, workspaces, roles);
+        const hasWorkspaces = nav.workspaces !== undefined && nav.workspaces.length > 0;
+        if (hasWorkspaces && visibleWorkspaces.length === 0)
+            continue;
+        result.push({
+            id: nav.id,
+            labels: entryAsLabels(translations[nav.label] ?? {}),
+            ...(nav.screen !== undefined && { screen: nav.screen }),
+            ...(nav.parent !== undefined && { parent: nav.parent }),
+            workspaces: visibleWorkspaces,
+        });
+    }
+    return result;
+}
+function lastSegment(qualifiedId) {
+    const idx = qualifiedId.lastIndexOf(":");
+    return idx === -1 ? qualifiedId : qualifiedId.slice(idx + 1);
+}
+function buildScreens(screens, navs, workspaces, translations, roles) {
+    const allNavs = [...navs.values()];
+    const result = [];
+    for (const [, screen] of screens) {
+        // An opted-out screen must not reach the manifest at all — the tool catalog
+        // builds `navigate`'s screen-id enum straight from `manifest.screens`.
+        if (!isAgentVisibleScreen(screen))
+            continue;
+        const matchingNavs = allNavs.filter((nav) => nav.screen === screen.id);
+        const accessibleNavs = matchingNavs.filter((nav) => uiVisible(nav.access, roles));
+        // A screen with no nav pointing at it is a detail view, reached only via
+        // navigation from a list row — never hidden by nav/workspace gating.
+        const reachable = matchingNavs.length === 0 ||
+            accessibleNavs.some((nav) => {
+                if (!nav.workspaces || nav.workspaces.length === 0)
+                    return true;
+                return visibleWorkspaceIds(nav.workspaces, workspaces, roles).length > 0;
+            });
+        if (!uiVisible(screen.access, roles) || !reachable)
+            continue;
+        const shortId = lastSegment(screen.id);
+        const screenWorkspaces = dedupeSorted(accessibleNavs.flatMap((nav) => visibleWorkspaceIds(nav.workspaces, workspaces, roles)));
+        result.push({
+            id: screen.id,
+            type: screen.type,
+            titles: labelsForSuffix(translations, `screen:${shortId}.title`),
+            // `screen.description` may be a raw i18n key (`registry.getAllTranslations()`
+            // double-prefixes it, see build-app-schema.ts:77-81) — match on suffix like
+            // `labelsForSuffix` does for entity/field labels, else fall back to the
+            // literal string as authored.
+            ...(screen.description !== undefined && {
+                description: labelsForSuffix(translations, screen.description)["en"] ?? screen.description,
+            }),
+            ...("entity" in screen && screen.entity !== undefined && { entity: screen.entity }),
+            // A detail screen takes the row id; everything else is parameterless.
+            params: screen.detailFor !== undefined ? ["id"] : [],
+            workspaces: screenWorkspaces,
+            ...(screen.detailFor !== undefined && { detailFor: screen.detailFor }),
+            ...("handler" in screen && typeof screen.handler === "string" && { handler: screen.handler }),
+        });
+    }
+    return result;
+}
+function buildWorkspaces(workspaces, translations, roles) {
+    const result = [];
+    for (const [, workspace] of workspaces) {
+        if (!uiVisible(workspace.access, roles))
+            continue;
+        result.push({
+            id: workspace.id,
+            labels: entryAsLabels(translations[workspace.label] ?? {}),
+            ...(workspace.default === true && { default: true }),
+        });
+    }
+    return result;
+}
+/** Registry snapshot → AI-agent manifest. Pure, deterministic, no I/O — mirrors
+ *  `buildToolCatalog`'s contract, just describing the app's shape instead of
+ *  generating callable tools from it. */
+export function buildAgentManifest(registry, options) {
+    const translations = registry.getAllTranslations();
+    const workspaceMap = registry.getAllWorkspaces();
+    const navMap = registry.getAllNavs();
+    const { roles } = options;
+    const features = buildFeatures(registry.features);
+    const entities = buildEntities(registry.getAllEntities(), translations, (name) => registry.getSearchableFields(name));
+    const handlers = buildHandlers(registry.getAllQueryHandlers(), registry.getAllWriteHandlers(), roles, (qn) => registry.getHandlerEntity(qn), new Set(options.denyQns ?? []));
+    const screenMap = registry.getAllScreens();
+    const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
+    const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles);
+    const workspaces = buildWorkspaces(workspaceMap, translations, roles);
+    return {
+        builtForRoles: [...roles],
+        features: sortedByKey(features, (f) => f.name),
+        entities: sortedByKey(entities, (e) => e.name),
+        handlers: sortedByKey(handlers, (h) => h.qn),
+        screens: sortedByKey(screens, (s) => s.id),
+        navs: sortedByKey(navs, (n) => n.id),
+        workspaces: sortedByKey(workspaces, (w) => w.id),
+        tenantSettings: {
+            locale: options.locale,
+            ...(options.currency && { currency: options.currency }),
+        },
+    };
+}

package/dist/agent-tools/feature.d.ts

@@ -0,0 +1,3 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare const AGENT_TOOLS_FEATURE_NAME = "agent-tools";
+export declare function createAgentToolsFeature(): FeatureDefinition;

package/dist/agent-tools/feature.js

@@ -0,0 +1,29 @@
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint.js";
+export const AGENT_TOOLS_FEATURE_NAME = "agent-tools";
+export function createAgentToolsFeature() {
+    return defineFeature(AGENT_TOOLS_FEATURE_NAME, (r) => {
+        r.describe("Builds a tool catalog and an agent manifest from the mounted registry so an LLM agent can call handlers and understand the app's shape. A handler or entity without a `description` stays invisible to the agent by construction (see `resolveAgentExposure`), while a screen stays visible unless it opts out with `agent: { expose: false }` (see `isAgentVisibleScreen`) — this feature surfaces the resulting gaps at boot and via `kumiko agent lint` so an app author notices before an agent silently can't see a feature.");
+        r.uiHints({
+            displayLabel: "AI Agent Tools",
+            category: "ai",
+            recommended: false,
+        });
+        // Warns instead of throwing: undocumented handlers/screens/entities are a
+        // usability gap for the agent, not an invalid app — failing the boot here
+        // would turn every incrementally-documented app into an outage.
+        r.bootCheck(({ features }) => {
+            const gaps = findAgentDocGaps(features);
+            if (gaps.length === 0) {
+                // skip: no documentation gaps, nothing to warn about
+                return;
+            }
+            // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps
+            console.warn(`[agent-tools] ${gaps.length} handler/screen/entity gap(s) invisible to the AI agent — run \`kumiko agent lint\` for details:`);
+            for (const gap of gaps) {
+                // biome-ignore lint/suspicious/noConsole: operator-visibility at boot for agent-doc gaps
+                console.warn(`  ${formatAgentDocGap(gap)}`);
+            }
+        });
+    });
+}

package/dist/agent-tools/index.d.ts

@@ -0,0 +1,8 @@
+export type { AgentDocGap, AgentDocGapKind } from "./agent-doc-lint.js";
+export { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint.js";
+export { buildAgentManifest } from "./agent-manifest.js";
+export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.js";
+export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.js";
+export type { ToolCallRequest, ToolCallResult, ToolDispatcher } from "./tool-dispatch.js";
+export { dispatchToolCall } from "./tool-dispatch.js";
+export type { AgentManifest, AgentManifestEntity, AgentManifestFeature, AgentManifestField, AgentManifestHandler, AgentManifestNav, AgentManifestOptions, AgentManifestScreen, AgentManifestWorkspace, AgentToolMode, RegistryManifestView, RegistrySearchView, ToolCatalog, ToolCatalogOptions, ToolDefinition, ToolDispatchDescriptor, } from "./types.js";

package/dist/agent-tools/index.js

@@ -0,0 +1,5 @@
+export { AgentDocGapKinds, findAgentDocGaps, formatAgentDocGap } from "./agent-doc-lint.js";
+export { buildAgentManifest } from "./agent-manifest.js";
+export { AGENT_TOOLS_FEATURE_NAME, createAgentToolsFeature } from "./feature.js";
+export { buildToolCatalog, OPEN_FORM_TOOL_NAME, toolNameForQn } from "./tool-catalog.js";
+export { dispatchToolCall } from "./tool-dispatch.js";

package/dist/agent-tools/tool-catalog.d.ts

@@ -0,0 +1,28 @@
+import type { AgentManifest, RegistrySearchView, ToolCatalog, ToolCatalogOptions } from "./types.js";
+/** Drops the `query`/`write` verb segment from a handler QN, joins the rest with `_`, and
+ *  sanitizes to a valid tool-call identifier. Only the FIRST matching segment is dropped —
+ *  QNs are `<feature>:query|write:<entity>:<verb>`, so the verb only ever appears once at that
+ *  position; a blanket filter could accidentally eat a legitimately-named later segment. */
+export declare function toolNameForQn(qn: string): string;
+export declare const OPEN_FORM_TOOL_NAME = "open_form";
+/** Registry snapshot + role-filtered manifest → agent tool catalog. Pure, deterministic, no I/O
+ *  — every tool here is a name+schema only; `tool-dispatch.ts` is what actually calls a
+ *  permission-checked handler when the LLM invokes one of these by name.
+ *
+ *  `search_<entity>` / `find_<entity>_by_<field>` iterate mounted `:list` handlers directly off
+ *  the registry (unchanged from the original design). `get_<entity>` / `list_<entity>` are also
+ *  enumerated from the registry rather than `manifest.handlers`, because entity CRUD handlers
+ *  carry no `description`/`agent` and are therefore never role-exposed into the manifest (see
+ *  `resolveAgentExposure`) — the manifest can't tell us these handlers exist at all. Every other
+ *  tool (custom query/write handlers, navigate/open_form/ask_user) is manifest-derived, since
+ *  the manifest already carries the role-filtered handler/screen shape needed for those. Roles
+ *  and locale both come from the manifest (`manifest.builtForRoles` / `manifest.tenantSettings.locale`)
+ *  so the registry-derived and manifest-derived halves share one source and cannot disagree.
+ *
+ *  `options.denyQns` is the app-side cut, applied to both halves: it is the only way to keep a
+ *  handler out of the catalog that the app does not own (a bundled feature's), and the only way
+ *  to drop an entity CRUD tool, which no `agent.expose` on the manifest side can reach. It is
+ *  NOT read off the manifest on purpose — the manifest is prompt payload, and a list of the
+ *  handlers the model may not call has no business travelling to the provider. Pass the same
+ *  list to `buildAgentManifest` so the manifest stops describing what the catalog withholds. */
+export declare function buildToolCatalog(registry: RegistrySearchView, manifest: AgentManifest, options: ToolCatalogOptions): ToolCatalog;