@kazzle/app 0.1.726 → 0.1.727

package/dist/client.js

@@ -12,6 +12,9 @@
 //      app via the injected `KAZZLE_APP_COMPONENT_<NAME>_URL` env var. That URL
 //      is server-to-server only — never expose it to the browser.
 //
+// For thread vs Tools API branching, read `Kazzle-Tool-Context` via
+// `toolContext(req)` from `@kazzle/app/tools` (not this module).
+//
 // Dependency-free on purpose (uses global fetch). Do not add zod/vite here.
 /** Read the injected base URL of the Kazzle API for install-secret calls. */
 export function kazzleApiUrl() {

package/dist/tools.d.ts

@@ -1,4 +1,26 @@
 import type { z } from 'zod';
+/** Header Kazzle sets on every dispatched app-tool HTTP request. Source of truth: shared/tools/tool-invocation.types.ts */
+export declare const TOOL_CONTEXT_HEADER = "Kazzle-Tool-Context";
+export declare const ToolInvocationSource: {
+    readonly THREAD: "thread";
+    readonly API: "api";
+};
+export type ToolInvocationSource = typeof ToolInvocationSource[keyof typeof ToolInvocationSource];
+/** How this tool call was invoked — thread (AI / resume) vs Tools API. */
+export type ToolInvocationContext = {
+    source: typeof ToolInvocationSource.THREAD;
+    threadId: string;
+} | {
+    source: typeof ToolInvocationSource.API;
+};
+/**
+ * Read `Kazzle-Tool-Context` from an incoming tool handler request.
+ * Throws when the header is missing or malformed — only Kazzle dispatch should call the route.
+ */
+export declare function toolContext(req: Request): ToolInvocationContext;
+export declare function isThreadToolInvocation(context: ToolInvocationContext): context is Extract<ToolInvocationContext, {
+    source: typeof ToolInvocationSource.THREAD;
+}>;
 /** Zod schema for a tool's input object. Use .default(), .optional(), .transform(), etc. */
 export type KazzleToolInputSchema = z.ZodType<Record<string, unknown>>;
 export type ToolRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
@@ -19,7 +41,7 @@ export type KazzleTarget = ({
     type: 'kazzle';
     name: string;
 };
-export interface ToolInputButtonElement {
+export interface ToolActionButtonElement {
     type: 'button';
     id: string;
     label: string;
@@ -34,21 +56,27 @@ export interface ToolInputButtonElement {
     variant?: 'primary' | 'secondary' | 'destructive';
 }
 /**
- * A pending-input card element. Only buttons are rendered today; this stays a
+ * A required-action card element. Only buttons are rendered today; this stays a
  * union so form controls can be added later alongside their renderer.
  */
-export type ToolInputElement = ToolInputButtonElement;
-export interface KazzlePendingInput {
-    type: 'pending_input';
+export type ToolActionElement = ToolActionButtonElement;
+export interface ToolActionAssignee {
+    computerId?: string;
+    userId?: string;
+}
+export interface ToolActionSpec {
     title: string;
     description?: string;
-    elements: ToolInputElement[];
-    /**
-     * Optional card lifetime in milliseconds. When set, the framework stamps an
-     * absolute expiry, shows a countdown, and auto-presses the default-negative
-     * (Skip) on the client OR headlessly on the server if no client is connected.
-     * Omit for a card that waits indefinitely (its default negative reads Cancel).
-     */
+    elements: ToolActionElement[];
+    assignee?: ToolActionAssignee;
+    timeoutMs?: number;
+}
+export interface KazzleRequiredAction {
+    type: 'action_required';
+    title: string;
+    description?: string;
+    elements: ToolActionElement[];
+    assignee?: ToolActionAssignee;
     timeoutMs?: number;
 }
 interface KazzleToolBase {

package/dist/tools.js

@@ -16,6 +16,54 @@
 // server/apps/apps.skills.tools.ts — it reads the SAME shape defined here
 // (`name`, `displayName`, `description`, `input`, `target`).
 // If you change this contract, update that compiler and its tests together.
+//
+// Tool handlers (POST /tools/...) receive:
+//   - `Authorization: Bearer <install identity>` — scope secrets via KazzleInstallClient
+//   - `Kazzle-Tool-Context: <json>` — thread vs Tools API (`toolContext(req)`)
+// Handlers may return plain text, `{ content }`, or `{ type: "action_required", ... }`
+// to pause the thread until the user acts (see documents/tool-required-action.md).
+// Set `assignee.computerId` when only a specific device may fulfill the card.
+/** Header Kazzle sets on every dispatched app-tool HTTP request. Source of truth: shared/tools/tool-invocation.types.ts */
+export const TOOL_CONTEXT_HEADER = 'Kazzle-Tool-Context';
+export const ToolInvocationSource = {
+    THREAD: 'thread',
+    API: 'api',
+};
+/**
+ * Read `Kazzle-Tool-Context` from an incoming tool handler request.
+ * Throws when the header is missing or malformed — only Kazzle dispatch should call the route.
+ */
+export function toolContext(req) {
+    const raw = req.headers.get(TOOL_CONTEXT_HEADER);
+    if (!raw) {
+        throw new Error(`Missing ${TOOL_CONTEXT_HEADER} header — expected a Kazzle tool dispatch.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${TOOL_CONTEXT_HEADER} must be valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${TOOL_CONTEXT_HEADER} must be a JSON object.`);
+    }
+    const source = parsed.source;
+    if (source === ToolInvocationSource.API) {
+        return { source: ToolInvocationSource.API };
+    }
+    if (source === ToolInvocationSource.THREAD) {
+        const threadId = parsed.threadId;
+        if (typeof threadId !== 'string' || !threadId) {
+            throw new Error(`${TOOL_CONTEXT_HEADER} thread invocation requires threadId.`);
+        }
+        return { source: ToolInvocationSource.THREAD, threadId };
+    }
+    throw new Error(`${TOOL_CONTEXT_HEADER} source must be "thread" or "api".`);
+}
+export function isThreadToolInvocation(context) {
+    return context.source === ToolInvocationSource.THREAD;
+}
 /** Type-safe tools helper. Use: export const tools = defineTools([...]) */
 export function defineTools(tools) {
     return tools;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kazzle/app",
-  "version": "0.1.726",
+  "version": "0.1.727",
   "description": "Contracts, tool helpers, Vite helper, and templates for building Kazzle apps.",
   "license": "UNLICENSED",
   "repository": {

package/templates/ai-app/components/server/index.ts

@@ -35,7 +35,7 @@ import type { Context } from 'hono';
 import { cors } from 'hono/cors';
 
 const apiKey = process.env.KAZZLE_API_KEY;
-if (!apiKey) throw new Error('KAZZLE_API_KEY is required (mint with `api_key { action: "create" }`)');
+if (!apiKey) throw new Error('KAZZLE_API_KEY is required (mint with `api_key { create: {} }`)');
 const apiUrl = process.env.KAZZLE_API_URL;
 if (!apiUrl) throw new Error('KAZZLE_API_URL is required and must point at the matching Kazzle API environment');
 

package/templates/process-app/skills/tools/tools.ts

@@ -1,3 +1,6 @@
+// Tool handlers receive Kazzle-Tool-Context — read with toolContext(req) from
+// @kazzle/app/tools. Return { type: 'action_required', ... } only for thread
+// calls; from the Tools API return a normal domain error. See documents/apps.md.
 import { z } from 'zod';
 import type { KazzleTool } from '@kazzle/app/tools';