@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/agents/from-template.d.ts

@@ -0,0 +1,106 @@
+import { type ModelParameter } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { type ModelParams, type ModelRef } from "./definition.js";
+import { type AgentDefinitionInput } from "./instruction-files.js";
+import { type QuickAction } from "./profile.js";
+import { type TemplateRow } from "./templates.js";
+/** What the preview lists (P4-5): 带入 / 待配置 / 不可用. */
+export type PlanItemState = "carried" | "pending" | "unavailable";
+export type PlanItemKind = "instruction_file" | "description" | "quick_action" | "tool" | "skill" | "connector" | "subagent";
+/**
+ * One line of the preview. `reason` (a code) says why an item is pending or unavailable, and
+ * qualifies some carried ones:
+ * - instruction_file: unavailable `invalid_name`, `duplicate`, `too_many`, `too_long` (the joined
+ *   files exceed the agent's limit);
+ * - tool: `default` (the template names no tools: the defaults of a new agent), `subagents`
+ *   (`Agent` added because the template describes sub-agents); unavailable `plugin_unavailable`
+ *   (its plugin is not enabled in the org or not loaded), `unknown_tool`, `connector_key` (a
+ *   connector tool key: connectors carry over only through `connectors` entries);
+ * - skill: `pinned`, `not_pinned_manual_only`, `not_pinned_too_large`, `subagent` (named only by an
+ *   inline sub-agent); unavailable `not_found`;
+ * - connector: `several` (the first of several connectors made from the template was bound);
+ *   pending `no_connector`, `tools_missing` (the connector made from the template lacks every
+ *   named tool), `needs`; unavailable `template_not_found` (also for a template the org may not
+ *   see, named by the entry's reference only), `disallowed` (`disallowedTools` left none of its
+ *   tools), `invalid_endpoint` (a `needs` endpoint that is no http(s) URL);
+ * - subagent: unavailable `type_not_found`, `type_taken`, `too_many`.
+ */
+export interface PlanItem {
+    kind: PlanItemKind;
+    name: string;
+    state: PlanItemState;
+    reason?: string;
+}
+/** Where the chosen model comes from (P4-4). */
+export type ModelSource = "modelRef" | "tier" | "default" | "chosen";
+export interface PlannedModel {
+    ref: ModelRef;
+    params: ModelParams;
+    source: ModelSource;
+}
+/** The template's agent definition, without its model (chosen separately, P4-4). */
+export type PlannedDefinition = Omit<AgentDefinitionInput, "model" | "modelParams">;
+export interface TemplatePlan {
+    definition: PlannedDefinition;
+    /** The profile's description and quick actions. */
+    profile: {
+        description: string;
+        quickActions: QuickAction[];
+    };
+    /** The model the new agent gets (`opts.model` when given); null when the org has none. */
+    model: PlannedModel | null;
+    /** The automatic choice (P4-4), whatever `opts.model` is; what the dialog preselects. */
+    auto: PlannedModel | null;
+    items: PlanItem[];
+    /**
+     * What has no place in the agent or was cut to its limits: `maxSteps`, `effort` when the model
+     * does not declare it, `description` / `instructions` / `quickActions.<i>.title|body` /
+     * `instructionFiles.<i>.content` / `subagents.inline.<name>.description|instructions` when cut to
+     * the kernel's limits (UTF-16 units), `subagents.inline.<name>.tools.<key>` for a key the agent
+     * does not have, `connectors.<key>.tools.<name>` / `connectors.<key>.policies.<name>` for a tool
+     * the bound connector does not offer.
+     */
+    dropped: string[];
+    /** sha256 of the template id and version and everything resolved except the model. */
+    baseHash: string;
+    /** The first 16 hex digits of sha256 of the automatic model choice (ref and params). */
+    modelHash: string;
+    /** The preview hash: `<baseHash>.<modelHash>`. */
+    hash: string;
+}
+export interface PlanOptions {
+    /** Extension tools loaded on this replica (`ExtensionHost.tools()`). */
+    pluginTools: readonly {
+        plugin: string;
+        name: string;
+    }[];
+    /** Extensions enabled in the org. */
+    enabledPlugins: ReadonlySet<string>;
+    /** The model's parameter declarations, or null when the deployment cannot use it. */
+    resolveModel(ref: ModelRef): Promise<ModelParameter[] | null>;
+    /** The org's target of a model purpose, or null when unmapped. */
+    purpose(purpose: string): Promise<{
+        model: ModelRef;
+        params: ModelParams;
+    } | null>;
+    /**
+     * The org's default chat model. There is no such setting today: the first model of the first
+     * provider listed, as the agent form preselects (ruling P4-T3-2).
+     */
+    defaultModel(): Promise<ModelRef | null>;
+    /** The model the person chose (the automatic choice keeps its params when it is the same). */
+    model?: ModelRef;
+}
+/**
+ * `s` cut to `max` UTF-16 units (what the kernel's zod schemas count), never splitting a
+ * surrogate pair.
+ */
+export declare function cutUtf16(s: string, max: number): string;
+/** The pending connector key of the template's `connectors[i]` (stable per entry). */
+export declare const pendingKeyOf: (i: number) => string;
+/**
+ * Resolves what `row`'s template carries into a new agent of `orgId` (P4-4, P4-5, P4-6). Never
+ * throws for the org's state: what does not resolve is listed and left out, and text is cut to
+ * the kernel's limits; the result is checked against the agent and profile schemas.
+ */
+export declare function planFromTemplate(db: KernelSchemaDb, orgId: string, row: TemplateRow, opts: PlanOptions): Promise<TemplatePlan>;