@intentface/latch-agent-builder 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intentface
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @intentface/latch-agent-builder
+
+Agents defined as **data**, plus the meta-agent that writes that data. Ship a product where users create and edit their own agents in a chat, without deploying code.
+
+## What it does
+
+- **`AgentRecordSchema`** (`@intentface/latch-agent-builder/record`) — one zod schema for what an agent *is*: name, scope, instructions, model, connections, and capability flags under `exec` (sandbox, memory, authored tools, reasoning effort). The model that writes a record, the editor a user types into, and the validator that guards the save all speak this one shape. The subpath is zod-only and browser-safe, so a form can import it.
+- **`normalizeAgentRecord` / `parseAgentRecord`** — the canonical form: name normalization, trimming, deduped memory targets, dropped blanks. Cross-field rules live in the schema, so an org-scoped memory config on a user-scoped agent is rejected once, not in three places.
+- **`createAgentBuilder`** — the meta-agent. It reads the host's models, connections and chat history to make grounded proposals, then creates and updates agents through a host-supplied store. Mutations are gated with `user-approval`, so a user sees the exact spec before it persists.
+- **`AgentBuilderStore`** — the storage seam. `@intentface/latch-drizzle` ships an implementation; a host with its own tables can satisfy it directly.
+- **`AgentBuilderExtension`** — the feature seam. Evals, tool authoring, memory schemas and connection management plug in as extensions, so a host without the feature gets a builder that never mentions it.
+
+## Usage
+
+```ts
+import { createAgentBuilder } from "@intentface/latch-agent-builder";
+
+const builder = createAgentBuilder<Principal>({
+  model,
+  // Lazy and per-principal, so the composition root has no import cycle.
+  deps: async (principal) => ({ runtime, store, models, connections }),
+  extensions: [evalsExtension, toolAuthoringExtension],
+});
+```
+
+Register it like any other agent, and the records it writes resolve into live agents through the store.
+
+## Where it fits
+
+Sits on `@intentface/latch-core` — the records it produces become agent factories the runtime can run. Pair it with `@intentface/latch-drizzle` for the store.

package/dist/agent-builder.d.ts

@@ -0,0 +1,105 @@
+import type { AgentFactory, AgentMeta, Runtime } from "@intentface/latch-core";
+import type { LanguageModel } from "ai";
+import type { AgentBuilderExtension } from "./extension";
+import type { AgentBuilderStore } from "./store";
+/** A model the builder may assign to an agent (from the host's catalog). */
+export interface ModelChoice {
+    id: string;
+    label?: string;
+    provider?: string;
+    reasoning?: boolean;
+}
+/** A connection the builder may wire to an agent. */
+export interface ConnectionChoice {
+    name: string;
+    kind?: string;
+    authorized?: boolean;
+}
+/** The live host services the builder's tools run against, per principal. */
+export interface AgentBuilderDeps<P> {
+    runtime: Pick<Runtime<P>, "listAgents" | "listChats" | "loadHistory" | "runAgent" | "schedule" | "listSchedules" | "unschedule">;
+    store: AgentBuilderStore<P>;
+    /** The host's model catalog (assignable model ids). */
+    models: ModelChoice[];
+    /** Connections the caller can wire to an agent. */
+    listConnections: (principal: P) => Promise<ConnectionChoice[]>;
+    /** Enumerate the tools a set of connections exposes, for this caller. */
+    connectionTools: (principal: P, names: string[]) => Promise<{
+        name: string;
+        description: string;
+    }[]>;
+}
+/**
+ * What THIS host actually wires for each optional agent capability — so the
+ * builder's prompt only offers what exists, and save_agent rejects the rest
+ * instead of persisting silent no-op flags. Every capability defaults to
+ * supported (backwards compatible for hosts that wire everything).
+ * `defaultTools` may carry a host-specific description of what the flag
+ * grants (rendered in the prompt verbatim).
+ */
+export interface CapabilitySupport {
+    sandbox?: boolean;
+    providerWebTools?: boolean;
+    renderTools?: boolean;
+    defaultTools?: boolean | {
+        description: string;
+    };
+    /**
+     * Whether the host honors the save-time write-approval waiver
+     * (`preApprovedWrites`). Only meaningful on hosts that gate writes; a host
+     * with ungated writes should declare it unsupported so the flag can't be
+     * saved as a no-op.
+     */
+    preApprovedWrites?: boolean | {
+        description: string;
+    };
+    /**
+     * Whether this host composes a memory provider (`exec.memory`). Opt-IN like
+     * `preApprovedWrites`: a host without memory must not let the builder save a
+     * memory config nothing will ever read.
+     */
+    memory?: boolean | {
+        description: string;
+    };
+}
+export interface AgentBuilderConfig<P, RuntimeContext = unknown> {
+    /** The builder's own model — a value, or a per-request factory (e.g. per-tenant catalogs). */
+    model: LanguageModel | ((ctx: {
+        context: RuntimeContext;
+        principal: P;
+    }) => LanguageModel | Promise<LanguageModel>);
+    /**
+     * Lazy host services, resolved per turn. Lazy so the host's composition
+     * root can import this package without a static import cycle.
+     */
+    deps: (principal: P) => Promise<AgentBuilderDeps<P>>;
+    /** Code-declared agent names save_agent must refuse to overwrite (host statics). */
+    reservedNames?: string[];
+    /** Which optional agent capabilities this host wires (default: all). */
+    capabilities?: CapabilitySupport;
+    /**
+     * Offer schedule tools (schedule_agent / list_schedules / unschedule_agent)
+     * so the builder can put agents on a cron cadence. Default true — the
+     * runtime always has the schedule API; disable if the host runs no cron
+     * driver (nothing would ever fire) or supplies richer schedule tools of its
+     * own via an extension. delete_agent's schedule cascade runs either way.
+     */
+    scheduling?: boolean;
+    /** Optional feature sets: evals, tool authoring, … */
+    extensions?: AgentBuilderExtension<P>[];
+    /**
+     * Interval (ms) for test_agent's progress heartbeat data part
+     * (`data-test-agent-progress`) while the nested test run executes. The
+     * heartbeat keeps idle-timeout proxies from killing the chat stream during
+     * a minutes-long test and doubles as live progress. Default 10s.
+     */
+    testHeartbeatMs?: number;
+    /** Picker metadata override. */
+    meta?: AgentMeta;
+}
+/**
+ * Create the Agent Builder as a standard agent factory for the host's
+ * registry: `agents: { "agent-builder": createAgentBuilder({...}) }`.
+ */
+export declare function createAgentBuilder<P, RuntimeContext = unknown>(config: AgentBuilderConfig<P, RuntimeContext>): AgentFactory<P, RuntimeContext>;
+//# sourceMappingURL=agent-builder.d.ts.map

package/dist/agent-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-builder.d.ts","sourceRoot":"","sources":["../src/agent-builder.ts"],"names":[],"mappings":"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"}