@kubuild/ai 0.8.1 → 0.8.2

package/dist/server/tools/helpers.d.cts

@@ -0,0 +1,66 @@
+import type { Node, PageDocument } from '@kubuild/schema';
+import { type DocumentSecurityLimits } from '@kubuild/core';
+import type { AiCompiledComponentSpec } from '../../types.cjs';
+import type { ToolExecutionResult } from './types.cjs';
+/**
+ * A failed tool call (STORA-530).
+ *
+ * Failures are deliberately *not* thrown: they're returned to the model as a normal
+ * `tool_result` with `ok: false` so it can read the reason, fix its arguments and retry.
+ * That self-correction loop is the main reason agent mode beats one-shot JSON generation —
+ * a hallucinated node id becomes a retry instead of a broken document.
+ */
+export declare function fail(summary: string, message: string, extra?: Record<string, unknown>): ToolExecutionResult;
+export declare function succeed(summary: string, content: Record<string, unknown>, rest?: Pick<ToolExecutionResult, 'op' | 'document'>): ToolExecutionResult;
+/** Reads a required string argument, tolerating the whitespace LLMs sometimes emit. */
+export declare function readString(input: Record<string, unknown>, key: string): string | null;
+export declare function readPlainObject(input: Record<string, unknown>, key: string): Record<string, unknown> | null;
+export declare function readOptionalIndex(input: Record<string, unknown>, key: string): number | undefined;
+/** Up to `limit` existing node ids most similar to a bad one, for the retry hint. */
+export declare function suggestNodeIds(document: PageDocument, badId: string, limit?: number): string[];
+export interface ResolvedNode {
+    node: Node;
+}
+/** Resolves a node id against the snapshot, or returns a retry-friendly failure. */
+export declare function resolveNode(document: PageDocument, nodeId: string, toolName: string): {
+    node: Node;
+} | {
+    error: ToolExecutionResult;
+};
+export declare function findCatalogEntry(catalog: AiCompiledComponentSpec[], type: string): AiCompiledComponentSpec | undefined;
+/**
+ * Enforces the registry's nesting contract before an insert/move (STORA-530).
+ *
+ * The same `acceptsChildren`/`allowedChildren` rules the prompt states are checked here,
+ * because a prompt rule is a suggestion while a tool check is a guarantee — and a document
+ * that violates them renders wrong rather than failing loudly.
+ *
+ * An empty catalog (host supplied no registry) means "unknown", so nesting is allowed
+ * rather than blocking every insert.
+ */
+export declare function checkNesting(catalog: AiCompiledComponentSpec[], parent: Node, childType: string): string | null;
+/** Validates a component type against the catalog, returning a retry hint when unknown. */
+export declare function checkComponentType(catalog: AiCompiledComponentSpec[], type: string): string | null;
+/**
+ * The defense-in-depth gate every write tool passes through before its op is accepted —
+ * the same `validateDocumentSecurity` pass `normalizeAndValidate*` already applies to
+ * generated documents, now applied per mutation so a single bad tool call can't smuggle
+ * a `javascript:` href or a prototype-pollution key into the snapshot.
+ */
+export declare function checkDocumentSecurity(document: PageDocument, limits?: DocumentSecurityLimits): string | null;
+/**
+ * Normalizes a model-authored node and guarantees its ids don't collide with the snapshot
+ * (`insertNode` in `@kubuild/core` throws on duplicate ids). Reuses the shared
+ * `normalizeNodeTree` so agent-authored nodes get the same prop/style coercions as nodes
+ * from full-page generation.
+ */
+export declare function normalizeIncomingNode(raw: unknown, document: PageDocument, options?: {
+    preserveIds?: boolean;
+}): {
+    node: Node;
+} | {
+    error: string;
+};
+/** Short human description of a node for tool summaries / op labels. */
+export declare function describeNode(node: Node): string;
+//# sourceMappingURL=helpers.d.cts.map

package/dist/server/tools/helpers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.cts","sourceRoot":"","sources":["../../../src/server/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAM3G;AAED,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,UAAU,CAAC,GAClD,mBAAmB,CAErB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrF;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIhC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjG;AAeD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAOzF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAYjD;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,uBAAuB,EAAE,EAClC,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAmBf;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAKf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,MAAM,GAAG,IAAI,CAIf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkCpC;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG/C"}

package/dist/server/tools/helpers.d.ts

@@ -1,7 +1,7 @@
 import type { Node, PageDocument } from '@kubuild/schema';
 import { type DocumentSecurityLimits } from '@kubuild/core';
-import type { AiCompiledComponentSpec } from '../../types';
-import type { ToolExecutionResult } from './types';
+import type { AiCompiledComponentSpec } from '../../types.js';
+import type { ToolExecutionResult } from './types.js';
 /**
  * A failed tool call (STORA-530).
  *

package/dist/server/tools/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/server/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAM3G;AAED,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,UAAU,CAAC,GAClD,mBAAmB,CAErB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrF;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIhC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjG;AAeD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAOzF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAYjD;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,uBAAuB,EAAE,EAClC,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAmBf;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAKf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,MAAM,GAAG,IAAI,CAIf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkCpC;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG/C"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/server/tools/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAIL,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAG9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,mBAAmB,CAM3G;AAED,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,IAAI,GAAG,UAAU,CAAC,GAClD,mBAAmB,CAErB;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrF;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAIhC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIjG;AAeD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CAOzF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,mBAAmB,CAAA;CAAE,CAYjD;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,uBAAuB,EAAE,EAClC,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAmBf;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,uBAAuB,EAAE,EAClC,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAKf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,sBAAsB,GAC9B,MAAM,GAAG,IAAI,CAIf;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkCpC;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAG/C"}

package/dist/server/tools/index.d.cts

@@ -0,0 +1,25 @@
+import type { AiToolDefinition } from '../../types.cjs';
+import type { AgentTool } from './types.cjs';
+export * from './types.cjs';
+export { READ_TOOLS } from './read-tools.cjs';
+export { WRITE_TOOLS } from './write-tools.cjs';
+export { checkNesting, checkComponentType, checkDocumentSecurity, normalizeIncomingNode, suggestNodeIds, } from './helpers.cjs';
+export interface DocumentToolsOptions {
+    /**
+     * Set false to give the agent a read-only tool set — useful for a "review my page"
+     * assistant that must never propose mutations.
+     */
+    allowWrites?: boolean;
+    /** Tool names to exclude, e.g. `['delete_node']` on a plan that forbids deletions. */
+    exclude?: string[];
+}
+/**
+ * The document tool set the agent is given (STORA-530).
+ *
+ * Read tools first: the ordering is what the model sees, and putting the "look before you
+ * edit" tools at the top nudges it toward reading a node before rewriting it.
+ */
+export declare function createDocumentTools(options?: DocumentToolsOptions): AgentTool[];
+/** Provider-facing definitions for a tool set. */
+export declare function toToolDefinitions(tools: AgentTool[]): AiToolDefinition[];
+//# sourceMappingURL=index.d.cts.map

package/dist/server/tools/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/server/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,EAAE,CAInF;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,gBAAgB,EAAE,CAExE"}

package/dist/server/tools/index.d.ts

@@ -1,9 +1,9 @@
-import type { AiToolDefinition } from '../../types';
-import type { AgentTool } from './types';
-export * from './types';
-export { READ_TOOLS } from './read-tools';
-export { WRITE_TOOLS } from './write-tools';
-export { checkNesting, checkComponentType, checkDocumentSecurity, normalizeIncomingNode, suggestNodeIds, } from './helpers';
+import type { AiToolDefinition } from '../../types.js';
+import type { AgentTool } from './types.js';
+export * from './types.js';
+export { READ_TOOLS } from './read-tools.js';
+export { WRITE_TOOLS } from './write-tools.js';
+export { checkNesting, checkComponentType, checkDocumentSecurity, normalizeIncomingNode, suggestNodeIds, } from './helpers.js';
 export interface DocumentToolsOptions {
     /**
      * Set false to give the agent a read-only tool set — useful for a "review my page"

package/dist/server/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzC,cAAc,SAAS,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,EAAE,CAInF;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,gBAAgB,EAAE,CAExE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,EAAE,CAInF;AAED,kDAAkD;AAClD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,gBAAgB,EAAE,CAExE"}

package/dist/server/tools/read-tools.d.cts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.cjs';
+export declare const READ_TOOLS: AgentTool[];
+//# sourceMappingURL=read-tools.d.cts.map

package/dist/server/tools/read-tools.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tools.d.cts","sourceRoot":"","sources":["../../../src/server/tools/read-tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4L5C,eAAO,MAAM,UAAU,EAAE,SAAS,EAA8D,CAAC"}

package/dist/server/tools/read-tools.d.ts

@@ -1,3 +1,3 @@
-import type { AgentTool } from './types';
+import type { AgentTool } from './types.js';
 export declare const READ_TOOLS: AgentTool[];
 //# sourceMappingURL=read-tools.d.ts.map

package/dist/server/tools/read-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/read-tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AA4LzC,eAAO,MAAM,UAAU,EAAE,SAAS,EAA8D,CAAC"}
+{"version":3,"file":"read-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/read-tools.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4L5C,eAAO,MAAM,UAAU,EAAE,SAAS,EAA8D,CAAC"}

package/dist/server/tools/types.d.cts

@@ -0,0 +1,51 @@
+import type { Node, PageDocument } from '@kubuild/schema';
+import type { DocumentSecurityLimits } from '@kubuild/core';
+import type { AgentOp, AiCompiledComponentSpec, AiToolDefinition } from '../../types.cjs';
+/**
+ * Everything a tool needs to answer or mutate (STORA-530).
+ *
+ * `document` is the agent's private **snapshot** — never the user's live canvas document.
+ * Write tools return an updated snapshot plus an `AgentOp`; the real document is only
+ * touched later, on the client, when the user applies the run.
+ */
+export interface ToolExecutionContext {
+    document: PageDocument;
+    catalog: AiCompiledComponentSpec[];
+    securityLimits?: DocumentSecurityLimits;
+    /**
+     * Delegate used by `insert_section` to synthesize a section node — wired to
+     * `KubuildAiEngine.generateSection` so section generation keeps going through the
+     * existing plan/normalize/validate path rather than a second implementation.
+     */
+    generateSection?: (params: {
+        prompt: string;
+        parentContext?: string;
+    }) => Promise<Node>;
+    signal?: AbortSignal;
+}
+export interface ToolExecutionResult {
+    ok: boolean;
+    /**
+     * Payload handed back to the model as a `tool_result` block. Always a JSON string, so
+     * the model sees a uniform shape whether the call succeeded or failed.
+     */
+    content: unknown;
+    /** One-line description for the run timeline / op review UI. */
+    summary: string;
+    /** Present on a successful write — the patch the client will replay. */
+    op?: AgentOp;
+    /** Present on a successful write — the snapshot later steps reason about. */
+    document?: PageDocument;
+}
+export interface AgentTool {
+    definition: AiToolDefinition;
+    /** Read tools never produce ops; write tools always do (when they succeed). */
+    kind: 'read' | 'write';
+    /**
+     * True for tools that can destroy user content. The editor refuses to auto-apply these
+     * even when the user has auto-apply turned on.
+     */
+    destructive?: boolean;
+    execute(input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolExecutionResult> | ToolExecutionResult;
+}
+//# sourceMappingURL=types.d.cts.map

package/dist/server/tools/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../../../src/server/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CACL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACvD"}

package/dist/server/tools/types.d.ts

@@ -1,6 +1,6 @@
 import type { Node, PageDocument } from '@kubuild/schema';
 import type { DocumentSecurityLimits } from '@kubuild/core';
-import type { AgentOp, AiCompiledComponentSpec, AiToolDefinition } from '../../types';
+import type { AgentOp, AiCompiledComponentSpec, AiToolDefinition } from '../../types.js';
 /**
  * Everything a tool needs to answer or mutate (STORA-530).
  *

package/dist/server/tools/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEtF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CACL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACvD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEzF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,gBAAgB,CAAC;IAC7B,+EAA+E;IAC/E,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CACL,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACvD"}

package/dist/server/tools/write-tools.d.cts

@@ -0,0 +1,3 @@
+import type { AgentTool } from './types.cjs';
+export declare const WRITE_TOOLS: AgentTool[];
+//# sourceMappingURL=write-tools.d.cts.map

package/dist/server/tools/write-tools.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-tools.d.cts","sourceRoot":"","sources":["../../../src/server/tools/write-tools.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,YAAY,CAAC;AAslBvF,eAAO,MAAM,WAAW,EAAE,SAAS,EASlC,CAAC"}

package/dist/server/tools/write-tools.d.ts

@@ -1,3 +1,3 @@
-import type { AgentTool } from './types';
+import type { AgentTool } from './types.js';
 export declare const WRITE_TOOLS: AgentTool[];
 //# sourceMappingURL=write-tools.d.ts.map

package/dist/server/tools/write-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/write-tools.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,SAAS,CAAC;AAslBpF,eAAO,MAAM,WAAW,EAAE,SAAS,EASlC,CAAC"}
+{"version":3,"file":"write-tools.d.ts","sourceRoot":"","sources":["../../../src/server/tools/write-tools.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAA6C,MAAM,YAAY,CAAC;AAslBvF,eAAO,MAAM,WAAW,EAAE,SAAS,EASlC,CAAC"}