@frockbot/applet-sdk 0.7.160 → 0.7.161

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/applet-sdk",
-  "version": "0.7.160",
+  "version": "0.7.161",
   "private": false,
   "type": "module",
   "description": "Authoring SDK for FrockBot Applets: schema-first Durable Object server, TanStack DB client, component kit, linter, and the build pipeline.",

package/plugin/index.d.ts

@@ -442,60 +442,294 @@ export interface PluginHookContext extends PluginContext {
   readonly event: PluginHookEvent;
 }
 
+/** The kinds of Turn the kernel admits. */
+export type TurnType = "chat" | "agent" | "automation" | "subagent";
+
+/** The agent a hook is running inside, as a hook payload carries it. */
+export interface AgentSnapshot {
+  botId: string;
+  agentId: string;
+  sessionId: string;
+  status: "idle" | "running" | "disposed";
+}
+
 /** One step of the loop, as a hook payload carries it. */
-export interface StepSnapshot {
+export interface StepSnapshot extends AgentSnapshot {
+  compositionGenerationId: string;
+  turn: number;
   step: number;
-  [key: string]: unknown;
+  turnType: TurnType;
+  subagentRole?: string;
 }
 
-/** One tool as the model is offered it. */
+/**
+ * One tool as the model is offered it. Exactly these three members: a tool
+ * returned from `agent/tool-exposure` with any other member is refused.
+ */
 export interface ToolSchema {
   name: string;
   description: string;
   inputSchema: JsonSchema;
-  [key: string]: unknown;
+}
+
+/** What the system prompt is being assembled for. */
+export interface PromptAssemblyContext {
+  sessionId: string;
+  provider: string;
+  model: string;
+  turnType: TurnType;
+  subagentRole?: string;
+  /** The step being assembled (1-based) and the last step the loop will run. */
+  step?: { current: number; max: number };
+  /** The Turn's deadline and the assembly instant, Unix epoch milliseconds. */
+  deadline?: { at: number; now: number };
+}
+
+/** The assembled system prompt: its text, and the sections it was built from. */
+export interface PromptAssembly {
+  text: string;
+  sections: Array<{ id: string; text: string }>;
+}
+
+/** One tool call the model made. `input` is whatever the model sent. */
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+/** The call a tool hook is about, minus anything live. */
+export interface ToolCallContext {
+  botId: string;
+  agentId: string;
+  sessionId: string;
+  compositionGenerationId: string;
+  effectId: string;
+  toolCall?: ToolCall;
+  turnType: TurnType;
+  subagentRole?: string;
+}
+
+/**
+ * The durable root an attachment's bytes live in, as the kernel records it.
+ * Unlike {@link WorkspaceRoot}, which a Plugin names and the authority
+ * completes, this one carries the User id.
+ */
+export type AttachmentRoot =
+  | { kind: "bot-instructions"; userId: string; botId: string }
+  | { kind: "user-instructions"; userId: string }
+  | { kind: "bot-memory"; userId: string; botId: string }
+  | { kind: "user-memory"; userId: string }
+  | { kind: "project-memory"; userId: string; projectId: string }
+  | {
+      kind: "package-declared";
+      userId: string;
+      packageId: string;
+      rootId: string;
+    };
+
+/** Where an attachment's bytes live: a durable root and a relative path. */
+export interface AttachmentPath {
+  root: AttachmentRoot;
+  path: string;
+}
+
+/** A binary a tool produced, named by where it lives rather than by its bytes. */
+export interface ToolAttachment {
+  kind: "image";
+  mediaType: "image/png" | "image/jpeg" | "image/webp";
+  workspacePath: AttachmentPath;
+  contentHash: string;
+  bytes: number;
+  /** Resolved bytes, present only in memory for one model request. */
+  dataBase64?: string;
+}
+
+/**
+ * A tool's settled result, as the loop records it. Not {@link ToolResult},
+ * which is what a Plugin's own `execute` answers with.
+ */
+export interface ToolCallResult {
+  content: string;
+  isError: boolean;
+  /** The Turn ends once this result is recorded. */
+  endsTurn?: boolean;
+  attachments?: ToolAttachment[];
+}
+
+/**
+ * Whether a call is ready to run or already answered. A hook may deny a ready
+ * call with a result; it may not lift a denial or change the call.
+ */
+export type ToolPreparation =
+  | { kind: "ready"; call: ToolCall; idempotent: boolean }
+  | { kind: "denied"; call: ToolCall; result: ToolCallResult };
+
+/** Provider content the kernel replays on later turns; opaque to a Plugin. */
+export interface ModelReplayState {
+  connectionId?: string;
+  connectionGeneration?: string;
+  provider: string;
+  model: string;
+  content: string;
+}
+
+/** One message in a model request. */
+export type ModelMessage =
+  | { role: "user"; content: string }
+  | {
+      role: "assistant";
+      content: string;
+      toolCalls: ToolCall[];
+      providerState?: ModelReplayState;
+    }
+  | {
+      role: "tool";
+      callId: string;
+      name: string;
+      content: string;
+      isError: boolean;
+      attachments?: ToolAttachment[];
+    };
+
+/** The JSON Schema subset a structured response may be held to. */
+export type StructuredOutputSchema =
+  | {
+      type: "object";
+      properties?: Record<string, StructuredOutputSchema>;
+      required?: string[];
+      additionalProperties?: boolean;
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    }
+  | {
+      type: "array";
+      items: StructuredOutputSchema;
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    }
+  | {
+      type: "string" | "number" | "boolean";
+      enum?: unknown[];
+      title?: string;
+      description?: string;
+    };
+
+export type ModelResponseFormat =
+  | { type: "json_schema"; name: string; schema: StructuredOutputSchema }
+  | { type: "json" };
+
+/** The Connection a request was admitted under. */
+export interface ModelBinding {
+  connectionId: string;
+  connectionGeneration?: string;
+  catalogGeneration?: string;
+}
+
+/**
+ * One normalized model request. A hook may change `system`, `messages`,
+ * `tools` and `responseFormat`; a replacement that changes `requestId`,
+ * `provider`, `model` or `modelBinding` is refused.
+ */
+export interface ModelRequest {
+  requestId: string;
+  provider: string;
+  model: string;
+  system: string;
+  messages: ModelMessage[];
+  tools: ToolSchema[];
+  responseFormat?: ModelResponseFormat;
+  modelBinding?: ModelBinding;
+}
+
+/** A Bot's look as the person picked it. */
+export type BotLook = "inherit" | "studio" | "custom";
+
+/** The named looks a theme document is compiled from. */
+export type ThemeLook = "ink" | "paper" | "studio";
+
+/** Every colour is `#rrggbb`. */
+export interface ThemeSurfaces {
+  window: string;
+  surface: string;
+  raised: string;
+  text: string;
+  muted: string;
+  line: string;
+  accent: string;
+  onAccent: string;
+}
+
+export interface ThemeTokens {
+  surfaces: ThemeSurfaces;
+  type: "manrope" | "inter";
+  bubbles: { bot: "plain" | "raised"; me: "accent" | "tint" };
+}
+
+/** Tokens that take over from `after`, a 24-hour `HH:MM` time of day. */
+export interface ThemePhase {
+  after: string;
+  tokens: ThemeTokens;
+}
+
+/**
+ * The closed document the client paints a Bot from. The kernel re-validates a
+ * `theme/assemble` replacement and refuses one that has any other member,
+ * uses `approval`, `billing`, `Stop` or `grants` as a key anywhere, puts
+ * `text` under 4.5:1 against `window` or `surface`, `muted` under 3:1
+ * against `window`, or `onAccent` under 4.5:1 against `accent`, or has more
+ * than 24 `phases`. A refused document is charged to every Plugin that wraps
+ * `theme/assemble`, and the Bot keeps its last good theme.
+ */
+export interface ThemeDocument {
+  schemaVersion: 1;
+  look: ThemeLook;
+  tokens: ThemeTokens;
+  phases?: ThemePhase[];
 }
 
 /**
  * What each hook receives, and the one value it may replace. A hook returns
  * `undefined` to leave the value alone, or the replacement — the *whole*
  * value, not a patch. A later Plugin sees an earlier Plugin's replacement.
- * `agent/turn-stopping` is a notification: its return is ignored.
+ * `agent/turn-stopping` is a notification: it may not replace anything.
  */
 export interface PluginHookPayloads {
   "system-prompt/assemble": {
-    context: { [key: string]: unknown };
-    assembly: { [key: string]: unknown };
+    context: PromptAssemblyContext;
+    assembly: PromptAssembly;
   };
   "agent/tool-exposure": { step: StepSnapshot; tools: ToolSchema[] };
-  "agent/request": { step: StepSnapshot; request: { [key: string]: unknown } };
+  "agent/request": { step: StepSnapshot; request: ModelRequest };
   "tools/pre-execute": {
-    call: { [key: string]: unknown };
-    context: { [key: string]: unknown };
-    preparation: { [key: string]: unknown };
+    call: ToolCall;
+    context: ToolCallContext;
+    preparation: ToolPreparation;
   };
   "tools/post-execute": {
-    call: { [key: string]: unknown };
-    context: { [key: string]: unknown };
-    result: { [key: string]: unknown };
+    call: ToolCall;
+    context: ToolCallContext;
+    result: ToolCallResult;
   };
-  "agent/turn-stopping": { agent: { [key: string]: unknown }; turn: number };
+  "agent/turn-stopping": { agent: AgentSnapshot; turn: number };
   "theme/assemble": {
-    document: { [key: string]: unknown };
-    look: "inherit" | "studio" | "custom";
+    document: ThemeDocument;
+    look: BotLook;
     now: string;
     timezone: string;
   };
 }
 
 export interface PluginHookReplacements {
-  "system-prompt/assemble": PluginHookPayloads["system-prompt/assemble"]["assembly"];
+  "system-prompt/assemble": PromptAssembly;
   "agent/tool-exposure": ToolSchema[];
-  "agent/request": PluginHookPayloads["agent/request"]["request"];
-  "tools/pre-execute": PluginHookPayloads["tools/pre-execute"]["preparation"];
-  "tools/post-execute": PluginHookPayloads["tools/post-execute"]["result"];
+  "agent/request": ModelRequest;
+  "tools/pre-execute": ToolPreparation;
+  "tools/post-execute": ToolCallResult;
   "agent/turn-stopping": never;
-  "theme/assemble": PluginHookPayloads["theme/assemble"]["document"];
+  "theme/assemble": ThemeDocument;
 }
 
 export type PluginHook<Event extends PluginHookEvent> = (