@dex-ai/sdk 0.1.30

package/dist/create-agent.js

@@ -0,0 +1,205 @@
+/** createAgentImpl — wires extensions into an Agent instance. */
+import { runGenerate } from "./generate";
+import { resolveConfig, cleanCacheDir, TOOL_RESULT_CACHE_KEY, } from "./tool-result-cache";
+import { Messages } from "./messages";
+export function resolveModel(extensions, providerName, modelId) {
+    for (const ext of extensions) {
+        if (ext.name !== providerName || !ext.models)
+            continue;
+        const model = ext.models.find((m) => m.id === modelId);
+        if (model)
+            return model;
+    }
+    throw new Error(`No model "${modelId}" found on provider "${providerName}".`);
+}
+export async function createAgentImpl(opts) {
+    const extensions = opts.extensions ?? [];
+    // Seed messages (non-system) to append after system prompt assembly
+    const seedMessages = [];
+    if (opts.messages) {
+        seedMessages.push(...opts.messages);
+    }
+    // NOTE: We intentionally do NOT eagerly validate the model here.
+    // actx.model is a lazy getter — it will throw on first generate() call
+    // if the provider/model combination is invalid.  This allows the agent
+    // (and its TUI) to start up and let the user fix configuration via
+    // /model or /provider commands.
+    const messageStore = new Messages();
+    const actx = Object.defineProperties({
+        name: opts.name ?? "agent",
+        extensions,
+        messages: messageStore.array,
+        messageStore,
+        tokenCount: 0,
+        state: new Map(),
+        providerName: opts.provider,
+        modelId: opts.model,
+        appendMessage(message) {
+            messageStore.append(message);
+        },
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+        ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+    }, {
+        model: {
+            get() {
+                return resolveModel(extensions, actx.providerName, actx.modelId);
+            },
+            enumerable: true,
+        },
+    });
+    // ── Agent setup is a batch: validation deferred until all messages are
+    // in place (extensions may append history during init, system prompt is
+    // assembled after, then reordered). ──
+    messageStore.batch();
+    // init() on each extension (registration order).
+    for (const ext of extensions) {
+        if (ext.init)
+            await ext.init(actx);
+    }
+    // ── Tool result cache setup ──────────────────────────────────────────
+    if (opts.toolResultCache) {
+        const cacheConfig = resolveConfig(opts.toolResultCache);
+        actx.state.set(TOOL_RESULT_CACHE_KEY, cacheConfig);
+        await cleanCacheDir(cacheConfig);
+    }
+    // ── Assemble system prompt ──────────────────────────────────────────
+    // We consolidate all system-level content (systemPrompt + skills +
+    // session-start context) into a single system message. The last text
+    // block gets a cache_control breakpoint so providers that support
+    // prompt caching (Anthropic) can cache the static system prefix.
+    const systemParts = [];
+    // 1. Explicit system prompt from opts
+    if (opts.systemPrompt !== undefined) {
+        systemParts.push(opts.systemPrompt);
+    }
+    // 2. Collect skills from extensions — build catalog and store content in state
+    const skillMap = new Map();
+    const catalogLines = [];
+    for (const ext of extensions) {
+        const raw = ext.skills;
+        if (raw === undefined)
+            continue;
+        const list = Array.isArray(raw) ? raw : [raw];
+        for (const skill of list) {
+            if (skill.when) {
+                const active = await skill.when(actx);
+                if (!active)
+                    continue;
+            }
+            const text = typeof skill.content === "function"
+                ? await skill.content(actx)
+                : skill.content;
+            if (text) {
+                skillMap.set(skill.name, text);
+                const desc = skill.description ? `: ${skill.description}` : "";
+                catalogLines.push(`- **${skill.name}**${desc}`);
+            }
+        }
+    }
+    if (catalogLines.length > 0) {
+        systemParts.push(`## Available Skills\n\nUse the \`get_skill\` tool to retrieve detailed instructions when needed.\n\n${catalogLines.join("\n")}`);
+    }
+    actx.state.set("skills", skillMap);
+    // 3. Collect session-start context from extensions
+    const sessionContent = [];
+    for (const ext of extensions) {
+        const handler = ext.on?.["session-start"];
+        if (!handler)
+            continue;
+        try {
+            const result = await handler(actx);
+            if (result && Symbol.asyncIterator in result) {
+                for await (const c of result) {
+                    sessionContent.push(c);
+                }
+            }
+        }
+        catch {
+            /* observer */
+        }
+    }
+    // Extract text from session content and add to system parts
+    for (const c of sessionContent) {
+        if (c.type === "text") {
+            systemParts.push(c.text);
+        }
+    }
+    // Assemble the single system message with cache breakpoint on last block
+    if (systemParts.length > 0) {
+        const lastBlock = {
+            type: "text",
+            text: systemParts.join("\n\n"),
+            cacheControl: { type: "ephemeral" },
+        };
+        actx.appendMessage({
+            role: "system",
+            content: [lastBlock],
+        });
+    }
+    // Append any non-text session content as a separate context message
+    const nonTextSession = sessionContent.filter((c) => c.type !== "text");
+    if (nonTextSession.length > 0) {
+        actx.appendMessage({
+            role: "system",
+            content: nonTextSession,
+            type: "context-session",
+        });
+    }
+    // Ensure system messages are at the front (extensions may have appended
+    // conversation history during init() — e.g. session resume).
+    const allMsgs = [...messageStore.array];
+    const systemMsgs = allMsgs.filter((m) => m.role === "system");
+    const nonSystemMsgs = allMsgs.filter((m) => m.role !== "system");
+    messageStore._unsafeSetLength(0);
+    messageStore._unsafePush(...systemMsgs, ...nonSystemMsgs);
+    // Seed messages (non-system)
+    if (seedMessages.length > 0) {
+        for (const m of seedMessages) {
+            const withId = m.id !== undefined ? m : { ...m, id: crypto.randomUUID() };
+            messageStore._unsafePush(withId);
+        }
+    }
+    // End batch — validate the assembled message sequence.
+    messageStore.commit();
+    let disposed = false;
+    const agent = {
+        context: actx,
+        generate(o) {
+            if (disposed)
+                throw new Error("Agent has been disposed");
+            return runGenerate(actx, o);
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            // emit('session-stop') in reverse order
+            for (let i = extensions.length - 1; i >= 0; i--) {
+                const ext = extensions[i];
+                const handler = ext?.on?.["session-stop"];
+                if (handler) {
+                    try {
+                        await handler(actx);
+                    }
+                    catch {
+                        /* */
+                    }
+                }
+            }
+            // dispose() in reverse order
+            for (let i = extensions.length - 1; i >= 0; i--) {
+                const ext = extensions[i];
+                if (ext?.dispose) {
+                    try {
+                        await ext.dispose(actx);
+                    }
+                    catch {
+                        /* */
+                    }
+                }
+            }
+        },
+    };
+    return agent;
+}
+//# sourceMappingURL=create-agent.js.map

package/dist/create-agent.js.map

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

package/dist/extension.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Extension — the universal building block.
+ *
+ * Extensions contribute models, tools, skills, config, and event handlers.
+ * The agent loop emits events; extensions subscribe via `on`.
+ *
+ * Host-specific capabilities (e.g. CLI commands) are added by the host layer
+ * and discovered at runtime via duck typing — extensions don't need to know
+ * about every host that might load them.
+ */
+import type { ModelRequest } from "./provider";
+import type { ToolCall, ToolResult, AnyTool } from "./tool";
+import type { AgentContext, GenerateContext } from "./context";
+import type { Content, Message } from "./message";
+import type { Model } from "./model";
+import type { StandardSchemaV1 } from "./schema";
+export type MaybePromise<T> = T | Promise<T>;
+export interface ErrorSource {
+    readonly kind: "provider" | "tool" | "extension" | "loop";
+    readonly request?: ModelRequest;
+    readonly call?: ToolCall;
+    readonly extensionName?: string;
+    readonly event?: string;
+}
+/**
+ * A skill — structured instructions injected into the system prompt.
+ *
+ * Skills are context-sensitive guidance: coding patterns, tool usage hints,
+ * domain knowledge, etc. They can be static text or dynamically generated
+ * based on the current session state.
+ */
+export interface Skill {
+    /** Stable identifier, e.g. "memory.recall" or "coding.typescript". */
+    readonly name: string;
+    /** Short description shown in listings. */
+    readonly description?: string;
+    /**
+     * The skill content. Either:
+     *   - A static string (markdown/text injected as-is), or
+     *   - A function that generates content based on context.
+     */
+    readonly content: string | ((actx: AgentContext) => MaybePromise<string>);
+    /**
+     * When this skill should be active. If omitted, always active.
+     * Return false to suppress the skill for this session/generate.
+     */
+    readonly when?: (actx: AgentContext) => MaybePromise<boolean>;
+}
+/**
+ * Typed configuration schema for an extension.
+ *
+ * Extensions declare the config they accept. The host (CLI, SDK, ACP)
+ * validates user-supplied config against this schema at load time.
+ *
+ * Config values come from (in priority order):
+ *   1. Environment variables: DEX_<EXT_NAME>_<KEY> (uppercased, dot → underscore)
+ *   2. dex.config.ts → extensions section
+ *   3. Defaults declared here
+ */
+export interface ConfigField {
+    readonly type: "string" | "number" | "boolean" | "array" | "object";
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly required?: boolean;
+    /** Environment variable override name. Auto-generated if omitted. */
+    readonly env?: string;
+}
+/**
+ * Config schema — either a simple record of field descriptors,
+ * or a Standard Schema for full validation power.
+ */
+export type ConfigSchema = Record<string, ConfigField> | StandardSchemaV1;
+export interface ExtensionEvents {
+    "session-start"?: (actx: AgentContext) => MaybePromise<AsyncIterable<Content> | void>;
+    "session-stop"?: (actx: AgentContext) => MaybePromise<void>;
+    /**
+     * Fired before input messages are committed.
+     * Extensions can return additional Content to append to the last user message.
+     * Use this for attachments, context injection, etc.
+     */
+    "generate-input"?: (input: ReadonlyArray<Message>, gctx: GenerateContext) => MaybePromise<ReadonlyArray<Content> | void>;
+    "generate-start"?: (gctx: GenerateContext) => MaybePromise<AsyncIterable<Content> | void>;
+    "generate-stop"?: (gctx: GenerateContext) => MaybePromise<void>;
+    "model-start"?: (req: ModelRequest, gctx: GenerateContext) => MaybePromise<ModelRequest | void>;
+    "model-stop"?: (gctx: GenerateContext) => MaybePromise<void>;
+    "message-start"?: (gctx: GenerateContext) => MaybePromise<void>;
+    "message-stop"?: (message: Message, gctx: GenerateContext) => MaybePromise<void>;
+    "text-delta"?: (delta: string, gctx: GenerateContext) => MaybePromise<void>;
+    "reasoning-delta"?: (delta: string, gctx: GenerateContext) => MaybePromise<void>;
+    "tool-call-delta"?: (delta: {
+        toolCallId: string;
+        toolName: string;
+        inputDelta: string;
+    }, gctx: GenerateContext) => MaybePromise<void>;
+    "tool-start"?: (call: ToolCall, gctx: GenerateContext) => MaybePromise<ToolCall | ToolResult | void>;
+    "tool-stop"?: (result: ToolResult, gctx: GenerateContext) => MaybePromise<ToolResult | void>;
+    error?: (error: unknown, source: ErrorSource, gctx: GenerateContext) => MaybePromise<void>;
+}
+/**
+ * A single config field that a provider needs.
+ * Used by the CLI to prompt users during interactive provider setup.
+ */
+export interface ProviderConfigField {
+    /** Config key (e.g. "apiKey", "baseUrl"). */
+    readonly key: string;
+    /** Human-readable label shown during setup. */
+    readonly label: string;
+    /** Whether this field is required. */
+    readonly required: boolean;
+    /** If true, masks input (for API keys). */
+    readonly secret?: boolean;
+    /** Default value. */
+    readonly default?: string;
+    /** Environment variable fallback name. */
+    readonly envVar?: string;
+    /** Help text shown during input. */
+    readonly hint?: string;
+}
+/**
+ * A provider descriptor — declares config schema and factory.
+ * Exported by each provider package so the CLI can drive interactive setup.
+ */
+export interface ProviderDescriptor {
+    /** Provider type identifier (e.g. "openai", "anthropic"). */
+    readonly type: string;
+    /** Human-readable name (e.g. "OpenAI", "Anthropic"). */
+    readonly label: string;
+    /** Config fields this provider needs. */
+    readonly fields: ReadonlyArray<ProviderConfigField>;
+    /** Create a provider extension from a config object. */
+    create(config: Record<string, unknown>): Extension;
+}
+export interface Extension {
+    /** Stable identifier. For provider extensions, this is the provider name. */
+    readonly name: string;
+    /** Human-readable description of what this extension does. */
+    readonly description?: string;
+    /** Models this extension provides. */
+    readonly models?: ReadonlyArray<Model>;
+    /** Tools this extension contributes to the agent. */
+    readonly tools?: AnyTool | ReadonlyArray<AnyTool>;
+    /** Skills — structured instructions injected into the system prompt. */
+    readonly skills?: Skill | ReadonlyArray<Skill>;
+    /**
+     * Configuration schema. Declares the config keys this extension accepts.
+     * Values are resolved from env vars, dex.config.ts, and defaults.
+     */
+    readonly config?: ConfigSchema;
+    /** Event handlers. The loop emits events; extensions subscribe here. */
+    readonly on?: ExtensionEvents;
+    /** Called during Agent.create(). Seed long-lived resources. */
+    init?(actx: AgentContext): MaybePromise<void>;
+    /** Called during agent.dispose(). Release long-lived resources. Reverse order. */
+    dispose?(actx: AgentContext): MaybePromise<void>;
+}
+/**
+ * Extension namespace — identity-typed declaration helper.
+ */
+export declare const Extension: {
+    define<E extends Extension>(ext: E): E;
+};
+//# sourceMappingURL=extension.d.ts.map

package/dist/extension.d.ts.map

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

package/dist/extension.js

@@ -0,0 +1,20 @@
+/**
+ * Extension — the universal building block.
+ *
+ * Extensions contribute models, tools, skills, config, and event handlers.
+ * The agent loop emits events; extensions subscribe via `on`.
+ *
+ * Host-specific capabilities (e.g. CLI commands) are added by the host layer
+ * and discovered at runtime via duck typing — extensions don't need to know
+ * about every host that might load them.
+ */
+/**
+ * Extension namespace — identity-typed declaration helper.
+ */
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const Extension = {
+    define(ext) {
+        return ext;
+    },
+};
+//# sourceMappingURL=extension.js.map

package/dist/extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.js","sourceRoot":"","sources":["../src/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkOH;;GAEG;AACH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,SAAS,GAAG;IACxB,MAAM,CAAsB,GAAM;QACjC,OAAO,GAAG,CAAC;IACZ,CAAC;CACD,CAAC"}

package/dist/generate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The generate loop — event-driven.
+ *
+ * Emits events to extensions via ext.on['event-name']. Extensions subscribe
+ * to events they care about. The loop orchestrates model calls, tool dispatch,
+ * and context injection purely through events.
+ */
+import type { AgentContext, AgentStream, GenerateOptions } from "./index";
+export declare function runGenerate(actx: AgentContext, opts: GenerateOptions): AgentStream;
+//# sourceMappingURL=generate.d.ts.map

package/dist/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../src/generate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACX,YAAY,EACZ,WAAW,EAQX,eAAe,EAQf,MAAM,SAAS,CAAC;AAkQjB,wBAAgB,WAAW,CAC1B,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,eAAe,GACnB,WAAW,CAiBb"}