@k2b/cloud 0.29.1 → 0.30.0

package/src/ai/tool-sentences.ts

@@ -0,0 +1,38 @@
+import type { CapabilityPresentationCatalog } from "../contracts/capabilities";
+
+/**
+ * Sentences for Cloud's own Assistant tools that act on something, in the catalog shape every app uses for
+ * its Actions and keyed by tool name. The chat words these calls through the same renderer as app Actions;
+ * a test checks every placeholder against the tool's input schema. A tool that only reads or does several
+ * things, such as `memory` searching, adding, or forgetting, keeps its title with what it acted on instead.
+ */
+export const CLOUD_AI_TOOL_PRESENTATION = {
+  baseLocale: "en",
+  sentences: {
+    // Code asks for approvals of what it does inside the run, so a rejection or a stop does not mean the code did not run.
+    code_run: { approval: "Run code", done: "Ran code" },
+    code_action: { approval: "Run app action {input.action}", done: "Ran app action {input.action}" },
+    web_extract: { approval: "Read {input.url}", done: "Read {input.url}", notRun: "{input.url} not read" },
+    fetch_file: { approval: "Download {input.url}", done: "Downloaded {input.url}", notRun: "{input.url} not downloaded" },
+    write_file: { approval: "Write {input.path}", done: "Wrote {input.path}", notRun: "{input.path} not written" },
+  },
+  translations: {
+    de: {
+      actions: {
+        code_run: { sentences: { approval: "Code ausführen", done: "Code ausgeführt" } },
+        code_action: { sentences: { approval: "App-Aktion {input.action} ausführen", done: "App-Aktion {input.action} ausgeführt" } },
+        web_extract: { sentences: { approval: "{input.url} lesen", done: "{input.url} gelesen", notRun: "{input.url} nicht gelesen" } },
+        fetch_file: {
+          sentences: {
+            approval: "{input.url} herunterladen",
+            done: "{input.url} heruntergeladen",
+            notRun: "{input.url} nicht heruntergeladen",
+          },
+        },
+        write_file: {
+          sentences: { approval: "{input.path} schreiben", done: "{input.path} geschrieben", notRun: "{input.path} nicht geschrieben" },
+        },
+      },
+    },
+  },
+} as const satisfies CapabilityPresentationCatalog;

package/src/ai/types.ts

@@ -12,7 +12,8 @@ import type {
 } from "@k2b/nessi";
 import type { Usage } from "@k2b/nessi/ai";
 import type { z } from "zod";
-import type { CapabilityActionReview, CloudResourceRef } from "../contracts/capabilities";
+import type { CapabilitySentenceField } from "../_internal/capability-sentences";
+import type { CapabilityActionReview, CapabilityActionSentences, CloudResourceRef } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import type { AiTurnBlock } from "./protocol";
 
@@ -1025,6 +1026,12 @@ export type AiCapabilityToolPresentation = {
   appAccent?: string;
   title: string;
   capabilityKind: "query" | "action";
+  /** Actions: the app's sentences in the locale of the turn, worded for each call by the chat. */
+  sentences?: CapabilityActionSentences;
+  /** Actions: field formats for the sentences and labelled fields for the generic sentence, in schema order. */
+  fields?: CapabilitySentenceField[];
+  /** Actions: Cloud offered the model `approvalReason` for this call, so the chat may show it as the model's reason. */
+  approvalReason?: true;
 };
 
 export type AiToolPresentation = AiCapabilityToolPresentation;

package/src/api/admin-ai-skills.ts

@@ -1,6 +1,6 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
-import { getBuiltinAiSkillTemplates } from "../ai/skill-seeds";
+import { aiAppSkills } from "../ai/app-skill-store";
 import { AiSkillInputError, AiSkillLastAdminError, AiSkillRevisionConflictError, aiSkills } from "../ai/skills";
 import { AuthenticatedPrincipalSchema } from "../contracts/shared";
 import { type AuthContext, auth, err, fail, ok, respond, v } from "../server";
@@ -18,34 +18,52 @@ const SkillAccessUpdateSchema = z.object({ permission: z.enum(["read", "write",
 const notFound = (c: Parameters<typeof respond>[0], noun: string) => respond(c, fail(err.notFound(noun)));
 const conflict = (c: Parameters<typeof respond>[0], error: Error) => respond(c, { ok: false, error: error.message, status: 409 as const });
 
+const ConfirmedSchema = z.object({ confirmed: z.literal(true) }).strict();
+
+const installAppSkill = async (c: Parameters<typeof respond>[0], install: () => Promise<boolean>) => {
+  try {
+    return (await install()) ? respond(c, ok({ installed: true })) : notFound(c, "App Skill");
+  } catch (error) {
+    if (error instanceof AiSkillRevisionConflictError) return conflict(c, error);
+    if (error instanceof AiSkillInputError) return respond(c, fail(err.badInput(error.message)));
+    throw error;
+  }
+};
+
 export const createAdminAiSkillsRoutes = (authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin")) =>
   new Hono<AuthContext>()
     .use("*", authenticate)
     .get("/", v("query", ListSkillsSchema), async (c) => {
       const query = c.req.valid("query");
-      const [skills, summary] = await Promise.all([aiSkills.admin.list(query), aiSkills.admin.summary({ search: query.search })]);
+      const [skills, summary, appSkillIssues] = await Promise.all([
+        aiSkills.admin.list(query),
+        aiSkills.admin.summary({ search: query.search }),
+        aiAppSkills.appSkillIssues(),
+      ]);
       return respond(
         c,
         ok({
           ...skills,
           items: skills.items.map((skill) => ({ ...skill, id: skill.shortId })),
           summary,
+          appSkillIssues,
         }),
       );
     })
-    .get("/templates", (c) =>
-      respond(c, ok({ templates: getBuiltinAiSkillTemplates().map(({ key, version, name }) => ({ templateId: key, version, name })) })),
-    )
+    .get("/:skillId/app-version", async (c) => {
+      const skill = await aiSkills.admin.getByShortId(c.req.param("skillId")!);
+      if (!skill) return notFound(c, "Skill");
+      const version = await aiAppSkills.appVersion(skill.id);
+      return version ? respond(c, ok(version)) : notFound(c, "Skill");
+    })
     .post(
-      "/:skillId/template",
+      "/:skillId/reset",
       v(
         "json",
         z
           .object({
-            templateId: z.string().min(1),
-            templateVersion: z.number().int().positive(),
             expectedRevision: z.number().int().positive(),
-            mode: z.enum(["associate", "reset"]),
+            expectedAppVersion: z.string().regex(/^[a-f0-9]{64}$/),
             confirmed: z.literal(true),
           })
           .strict(),
@@ -54,22 +72,23 @@ export const createAdminAiSkillsRoutes = (authenticate: MiddlewareHandler<AuthCo
         const skill = await aiSkills.admin.getByShortId(c.req.param("skillId")!);
         if (!skill) return notFound(c, "Skill");
         try {
-          return (await aiSkills.admin.applyTemplate(skill.id, c.req.valid("json")))
+          const input = c.req.valid("json");
+          return (await aiAppSkills.reset(skill.id, input.expectedRevision, input.expectedAppVersion))
             ? respond(c, ok({ updated: true }))
             : notFound(c, "Skill");
         } catch (error) {
           if (error instanceof AiSkillRevisionConflictError) return conflict(c, error);
           if (error instanceof AiSkillInputError) return respond(c, fail(err.badInput(error.message)));
-          if (
-            typeof error === "object" &&
-            error !== null &&
-            (("code" in error && error.code === "23505") || ("errno" in error && error.errno === "23505"))
-          )
-            return conflict(c, new Error("A Skill with this name already exists."));
           throw error;
         }
       },
     )
+    .post("/apps/:appId/skills/:name/restore", v("json", ConfirmedSchema), (c) =>
+      installAppSkill(c, () => aiAppSkills.restore(c.req.param("appId")!, c.req.param("name")!)),
+    )
+    .post("/apps/:appId/skills/:name/adopt", v("json", ConfirmedSchema), (c) =>
+      installAppSkill(c, () => aiAppSkills.adopt(c.req.param("appId")!, c.req.param("name")!)),
+    )
     .get("/:skillId/projects", async (c) => {
       const skill = await aiSkills.admin.getByShortId(c.req.param("skillId")!);
       if (!skill) return notFound(c, "Skill");

package/src/api/fanout.ts

@@ -0,0 +1,128 @@
+/**
+ * Core's fan-out to many applications for one browser request, shared by Universal Search and dashboard widgets:
+ * bounded concurrency, one NDJSON line per application as soon as it finishes, and cancellation when the browser
+ * stops reading.
+ */
+
+/** Media type a client sends in `Accept` and receives back for a stream of JSON lines. */
+export const NDJSON_CONTENT_TYPE = "application/x-ndjson";
+
+export const ndjsonStreamHeaders = {
+  "content-type": `${NDJSON_CONTENT_TYPE}; charset=utf-8`,
+  // Each line must reach the browser when it is written: no cache, no transformation, no proxy buffering.
+  "cache-control": "no-store, no-transform",
+  "x-accel-buffering": "no",
+} as const;
+
+const encoder = new TextEncoder();
+export const ndjsonLine = (line: unknown) => `${JSON.stringify(line)}\n`;
+
+/**
+ * Starts `run` for every item with at most `concurrency` running at once, in item order. Each item's promise settles
+ * on its own, so a caller can act on fast items while slow ones still run. Aborting `signal` settles every item that
+ * has not finished as rejected and starts no further item.
+ */
+export const startBounded = <T, R>(
+  items: readonly T[],
+  concurrency: number,
+  run: (item: T, index: number) => Promise<R>,
+  signal?: AbortSignal,
+) => {
+  const deferred = items.map(() => {
+    let settled = false;
+    let resolve!: (result: PromiseSettledResult<R>) => void;
+    const promise = new Promise<PromiseSettledResult<R>>((done) => {
+      resolve = (result) => {
+        if (settled) return;
+        settled = true;
+        done(result);
+      };
+    });
+    return { promise, resolve };
+  });
+  const abort = () => {
+    const reason = signal?.reason ?? new Error("Fan-out deadline exceeded");
+    for (const entry of deferred) entry.resolve({ status: "rejected", reason });
+  };
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+  let next = 0;
+  void Promise.all(
+    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+      while (true) {
+        if (signal?.aborted) return;
+        const index = next;
+        next += 1;
+        const item = items[index];
+        if (item === undefined) return;
+        try {
+          deferred[index]?.resolve({
+            status: "fulfilled",
+            value: await run(item, index),
+          });
+        } catch (reason) {
+          deferred[index]?.resolve({ status: "rejected", reason });
+        }
+      }
+    }),
+  ).then(() => signal?.removeEventListener("abort", abort));
+  return deferred.map((entry) => entry.promise);
+};
+
+/** Waits for work that has already started, but no longer than `signal` allows. */
+export const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    // The work has already started; observe its rejection even if the client
+    // disconnected before we began waiting.
+    value.then(
+      (result) => {
+        signal.removeEventListener("abort", aborted);
+        resolve(result);
+      },
+      (error) => {
+        signal.removeEventListener("abort", aborted);
+        reject(error);
+      },
+    );
+    if (signal.aborted) return aborted();
+    signal.addEventListener("abort", aborted, { once: true });
+  });
+
+/**
+ * Answers with `first`, then one line per entry of `pending` in the order they finish, then `last(lines)`. A slow
+ * entry never holds back the others. When the client stops reading, `onCancel` runs so the caller can stop its work.
+ */
+export const ndjsonStream = <Line>(options: {
+  first: Line;
+  pending: readonly Promise<Line>[];
+  last: (lines: Line[]) => Line;
+  onCancel: () => void;
+}): Response => {
+  let cancelled = false;
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const write = (line: Line) => {
+        if (!cancelled) controller.enqueue(encoder.encode(ndjsonLine(line)));
+      };
+      write(options.first);
+      const lines: Line[] = [];
+      void Promise.all(
+        options.pending.map((pending) =>
+          pending.then((line) => {
+            lines.push(line);
+            write(line);
+          }),
+        ),
+      ).then(() => {
+        write(options.last(lines));
+        if (!cancelled) controller.close();
+      });
+    },
+    cancel() {
+      cancelled = true;
+      options.onCancel();
+    },
+  });
+  return new Response(body, { headers: ndjsonStreamHeaders });
+};

package/src/api/help.ts

@@ -13,21 +13,26 @@ export type HelpRouteDependencies = {
 
 export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
   const reader = dependencies.help ?? createHelpReader;
+  // Help is for signed-in people; the reader then hides apps the viewer may not see, like missing ones.
+  // Scoped to Help's paths: Core mounts these routes at its API root, before MCP and the other APIs.
   return new Hono<AuthContext>()
-    .use(dependencies.authenticate ?? auth.requireRole("*"))
+    .use("/help/v1/*", dependencies.authenticate ?? auth.requireRole("authenticated"))
+    .use("/help/v1/*", auth.requireOAuthScope("read", "admin"))
     .get("/help/v1/:appId/search", async (c) => {
       const locale = getLocale(c);
       const query = c.req.query("q")?.trim().slice(0, 200) ?? "";
       const payload: HelpSearchPayload = {
         locale,
-        ids: (await reader(locale).search({ query, appId: c.req.param("appId"), limit: 25 })).map((document) => document.documentId),
+        ids: (await reader(locale, c.get("actor")).search({ query, appId: c.req.param("appId"), limit: 25 })).map(
+          (document) => document.documentId,
+        ),
       };
       return c.json(payload);
     })
     .get("/help/v1/:appId/documents/:documentId", async (c) => {
       const locale = getLocale(c);
       const { t } = helpApiMessages.resolve([locale]);
-      const document = await reader(locale).read({ appId: c.req.param("appId"), documentId: c.req.param("documentId") });
+      const document = await reader(locale, c.get("actor")).read({ appId: c.req.param("appId"), documentId: c.req.param("documentId") });
       if (!document) return c.json({ code: "HELP_NOT_FOUND", message: t.notFound }, 404);
       const payload: HelpDocumentPayload = {
         locale: document.locale,

package/src/api/mcp.ts

@@ -481,7 +481,10 @@ const createMcpServer = (
       resolveLocale(request.headers, operatorDefault),
     ));
   const helpReader = async () =>
-    (dependencies.help ?? ((locale) => createHelpReader(locale, { listApps: registry })))(await resolveHelpLocale());
+    (dependencies.help ?? ((locale, viewer) => createHelpReader(locale, viewer, { listApps: registry })))(
+      await resolveHelpLocale(),
+      authority?.actor,
+    );
   const hasScope = (scope: "read" | "write"): boolean =>
     oauthScopes === null || oauthScopes.includes(scope) || oauthScopes.includes("admin");
   const requireScope = (scope: "read" | "write"): void => {

package/src/api/search.ts

@@ -18,6 +18,7 @@ import { searchInvocationOperation } from "../services/identity/invocation-opera
 import { normalizeInvocationRequestId, signInvocationToken } from "../services/identity/invocation-token";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import { LOCALE_HEADER } from "../shared/locale";
+import { ndjsonLine, ndjsonStream, ndjsonStreamHeaders, startBounded, waitWithin } from "./fanout";
 import {
   SEARCH_STREAM_CONTENT_TYPE,
   type SearchItem,
@@ -85,53 +86,6 @@ type SearchRouteDependencies = {
   withActiveSigner?: typeof withActiveIdentitySigner;
 };
 
-const startBounded = <T, R>(
-  items: readonly T[],
-  concurrency: number,
-  run: (item: T, index: number) => Promise<R>,
-  signal?: AbortSignal,
-) => {
-  const deferred = items.map(() => {
-    let settled = false;
-    let resolve!: (result: PromiseSettledResult<R>) => void;
-    const promise = new Promise<PromiseSettledResult<R>>((done) => {
-      resolve = (result) => {
-        if (settled) return;
-        settled = true;
-        done(result);
-      };
-    });
-    return { promise, resolve };
-  });
-  const abort = () => {
-    const reason = signal?.reason ?? new Error("Search fan-out deadline exceeded");
-    for (const entry of deferred) entry.resolve({ status: "rejected", reason });
-  };
-  signal?.addEventListener("abort", abort, { once: true });
-  if (signal?.aborted) abort();
-  let next = 0;
-  void Promise.all(
-    Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-      while (true) {
-        if (signal?.aborted) return;
-        const index = next;
-        next += 1;
-        const item = items[index];
-        if (item === undefined) return;
-        try {
-          deferred[index]?.resolve({
-            status: "fulfilled",
-            value: await run(item, index),
-          });
-        } catch (reason) {
-          deferred[index]?.resolve({ status: "rejected", reason });
-        }
-      }
-    }),
-  ).then(() => signal?.removeEventListener("abort", abort));
-  return deferred.map((entry) => entry.promise);
-};
-
 /** Highest app-provided priority first, then by title. */
 const rankItems = (items: SearchItem[]) => items.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0) || a.title.localeCompare(b.title));
 
@@ -139,38 +93,8 @@ const rankItems = (items: SearchItem[]) => items.sort((a, b) => (b.priority ?? 0
 const acceptsStream = (accept: string | undefined) =>
   accept?.split(",").some((type) => type.split(";")[0]?.trim().toLowerCase() === SEARCH_STREAM_CONTENT_TYPE) ?? false;
 
-const streamHeaders = {
-  "content-type": `${SEARCH_STREAM_CONTENT_TYPE}; charset=utf-8`,
-  // Each line must reach the browser when it is written: no cache, no transformation, no proxy buffering.
-  "cache-control": "no-store, no-transform",
-  "x-accel-buffering": "no",
-} as const;
-
-const encoder = new TextEncoder();
-const lineText = (line: SearchStreamLine) => `${JSON.stringify(line)}\n`;
-const encodeLine = (line: SearchStreamLine) => encoder.encode(lineText(line));
-
 type AppOutcome = { appId: string; status: SearchProviderStatus; items: SearchItem[]; ms: number };
 
-const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
-  new Promise<T>((resolve, reject) => {
-    const aborted = () => reject(signal.reason);
-    // The work has already started; observe its rejection even if the client
-    // disconnected before we began waiting.
-    value.then(
-      (result) => {
-        signal.removeEventListener("abort", aborted);
-        resolve(result);
-      },
-      (error) => {
-        signal.removeEventListener("abort", aborted);
-        reject(error);
-      },
-    );
-    if (signal.aborted) return aborted();
-    signal.addEventListener("abort", aborted, { once: true });
-  });
-
 /**
  * Creates the global search route.
  * Discovers search providers from the capability registry and fetches results via HTTP,
@@ -271,10 +195,16 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
         stream
           ? new Response(
               [
-                lineText({ type: "start", query: body.query, apps, providers: [], ...(body.unsupportedTags ? { unsupportedTags } : {}) }),
-                lineText({ type: "done", status: "complete", count: 0 }),
+                ndjsonLine({
+                  type: "start",
+                  query: body.query,
+                  apps,
+                  providers: [],
+                  ...(body.unsupportedTags ? { unsupportedTags } : {}),
+                } satisfies SearchStreamLine),
+                ndjsonLine({ type: "done", status: "complete", count: 0 } satisfies SearchStreamLine),
               ].join(""),
-              { headers: streamHeaders },
+              { headers: ndjsonStreamHeaders },
             )
           : c.json(body);
 
@@ -462,35 +392,30 @@ export const createSearchRoutes = (dependencies: SearchRouteDependencies = {}) =
       const failure = (outcome: AppOutcome) => outcome.status === "timeout" || outcome.status === "error";
 
       if (stream) {
-        let cancelled = false;
-        const body = new ReadableStream<Uint8Array>({
-          start(controller) {
-            const write = (line: SearchStreamLine) => {
-              if (!cancelled) controller.enqueue(encodeLine(line));
+        // A slow app never holds back the others: each line is written when its app finishes.
+        return ndjsonStream<SearchStreamLine>({
+          first: { type: "start", query: query.q, apps, providers: appIds, ...(unsupportedTags.length > 0 ? { unsupportedTags } : {}) },
+          pending: outcomes.map((pending) =>
+            pending.then(
+              (outcome): SearchStreamLine => ({
+                type: "provider",
+                provider: outcome.appId,
+                status: outcome.status,
+                results: outcome.items,
+                ms: outcome.ms,
+              }),
+            ),
+          ),
+          last: (lines) => {
+            const providerLines = lines.filter((line) => line.type === "provider");
+            return {
+              type: "done",
+              status: providerLines.some((line) => line.status === "timeout" || line.status === "error") ? "partial" : "complete",
+              count: providerLines.reduce((count, line) => count + line.results.length, 0),
             };
-            write({ type: "start", query: query.q, apps, providers: appIds, ...(unsupportedTags.length > 0 ? { unsupportedTags } : {}) });
-            let count = 0;
-            let partial = false;
-            // A slow app never holds back the others: each line is written when its app finishes.
-            void Promise.all(
-              outcomes.map((pending) =>
-                pending.then((outcome) => {
-                  count += outcome.items.length;
-                  partial ||= failure(outcome);
-                  write({ type: "provider", provider: outcome.appId, status: outcome.status, results: outcome.items, ms: outcome.ms });
-                }),
-              ),
-            ).then(() => {
-              write({ type: "done", status: partial ? "partial" : "complete", count });
-              if (!cancelled) controller.close();
-            });
-          },
-          cancel() {
-            cancelled = true;
-            streamCancelled.abort();
           },
+          onCancel: () => streamCancelled.abort(),
         });
-        return new Response(body, { headers: streamHeaders });
       }
 
       const finished = await Promise.all(outcomes);