@theokit/sdk 2.19.0 → 2.20.0

package/dist/generate-object.d.ts

@@ -1,5 +1,5 @@
-import type { ZodType } from "zod";
-import type { LocalOptions, ModelSelection } from "./types/agent.js";
+import type { z as ZodNamespace, ZodType } from "zod";
+import type { AgentOptions, LocalOptions, ModelSelection, SDKAgent } from "./types/agent.js";
 import type { ProviderRoutingSettings } from "./types/providers.js";
 /**
  * Options accepted by {@link Agent.generateObject}. Returns a typed object
@@ -16,6 +16,13 @@ export interface GenerateObjectOptions<T extends ZodType> {
     systemPrompt?: string;
     /** Model selection. Required (transient agents need a model). */
     model: ModelSelection;
+    /**
+     * M21 — optional separate model for the STRUCTURING step. When set, `model` first produces a
+     * free-text reasoned answer to the prompt (phase 1), then `structuringModel` extracts the
+     * schema-matched object by calling the `output` tool over that answer (phase 2). Lets a large
+     * model reason while a cheap fast model does the extraction. Absent ⇒ today's single-model flow.
+     */
+    structuringModel?: ModelSelection;
     /** API key. Falls back to env (THEOKIT_API_KEY etc). */
     apiKey?: string;
     /** Local runtime config (cwd, sandbox). Required to keep the transient agent local-only. */
@@ -76,3 +83,10 @@ export declare class GenerateObjectError extends Error {
     readonly cause?: unknown;
     constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
 }
+interface GenerateObjectDeps {
+    create: (options: AgentOptions) => Promise<SDKAgent>;
+    /** Hard-delete the transient agent from the registry after dispose. */
+    delete: (agentId: string) => Promise<void>;
+}
+export declare function generateObjectImpl<T extends ZodType>(options: GenerateObjectOptions<T>, deps: GenerateObjectDeps): Promise<GenerateObjectResult<ZodNamespace.infer<T>>>;
+export {};

package/dist/index.cjs

@@ -3813,6 +3813,24 @@ function salvagePartial(schema, raw) {
   }
   return out;
 }
+async function runReasoningPhase(options, deps) {
+  const reasoningOptions = {
+    model: options.model,
+    local: options.local,
+    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
+    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
+    ...options.providers !== void 0 ? { providers: options.providers } : {}
+  };
+  const reasoningAgent = await deps.create(reasoningOptions);
+  try {
+    const run = await reasoningAgent.send(options.prompt);
+    const result = await run.wait();
+    const text = result.result;
+    return typeof text === "string" ? text : options.prompt;
+  } finally {
+    await disposeAndDeleteTransient(reasoningAgent, deps.delete);
+  }
+}
 async function generateObjectImpl(options, deps) {
   const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(
     options.schema,
@@ -3835,8 +3853,11 @@ async function generateObjectImpl(options, deps) {
     }
     throw new CaptureSentinel(input);
   });
+  const reasoningText = options.structuringModel !== void 0 ? await runReasoningPhase(options, deps) : void 0;
+  const structuringModel = options.structuringModel ?? options.model;
+  const structuringPrompt = reasoningText ?? options.prompt;
   const agentOptions = buildTransientAgentOptions({
-    model: options.model,
+    model: structuringModel,
     local: options.local,
     outputTool,
     ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
@@ -3845,7 +3866,7 @@ async function generateObjectImpl(options, deps) {
   });
   const agent = await deps.create(agentOptions);
   try {
-    const userMessage = buildToolPrompt(options.prompt);
+    const userMessage = buildToolPrompt(structuringPrompt);
     let lastParseError;
     for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
       capturedRaw = void 0;
@@ -10803,23 +10824,27 @@ function tryParseSkill(raw, fallbackName, source, options) {
 
 // src/internal/runtime/skills/skills-manager.ts
 var SkillsManager = class {
-  constructor(cwd, _enabled, settingSourcesIncludeProject) {
+  constructor(cwd, _enabled, settingSourcesIncludeProject, skillsDir, inline) {
     this.cwd = cwd;
     this.settingSourcesIncludeProject = settingSourcesIncludeProject;
+    this.skillsDir = skillsDir;
+    this.inline = inline;
   }
   cwd;
   settingSourcesIncludeProject;
+  skillsDir;
+  inline;
   skills = [];
   async initialize() {
     if (!this.settingSourcesIncludeProject) {
-      this.skills = [];
+      this.skills = this.mergeInline([]);
       return;
     }
     await this.refresh();
   }
   async refresh() {
-    const skillsRoot = path.join(this.cwd, ".theokit", "skills");
-    this.skills = await discoverSkills(skillsRoot, {
+    const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
+    const discovered = await discoverSkills(skillsRoot, {
       onInvalidSkill: (info) => {
         process.stderr.write(
           `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
@@ -10827,6 +10852,13 @@ var SkillsManager = class {
         );
       }
     });
+    this.skills = this.mergeInline(discovered);
+  }
+  /** M22 — merge inline skills over discovered ones; inline wins on a name conflict. */
+  mergeInline(discovered) {
+    if (this.inline === void 0 || this.inline.length === 0) return discovered;
+    const inlineNames = new Set(this.inline.map((s) => s.name));
+    return [...discovered.filter((s) => !inlineNames.has(s.name)), ...this.inline];
   }
   list() {
     return Promise.resolve(this.skills);
@@ -10871,7 +10903,10 @@ function bootstrapSubmanagers(args) {
     out.skillsManager = new SkillsManager(
       args.workspaceCwd,
       args.options.skills?.enabled,
-      args.settingSourcesIncludeProject
+      args.settingSourcesIncludeProject,
+      // M22 — custom skills directory + inline (code-defined) skills.
+      args.options.skills?.skillsDir,
+      args.options.skills?.inline
     );
     const localSkills = out.skillsManager;
     out.skills = { list: () => localSkills.list() };
@@ -18773,6 +18808,20 @@ var Budget = class {
   }
 };
 
+// src/create-skill.ts
+function createSkill(spec) {
+  if (!spec.name) throw new Error("createSkill: `name` is required.");
+  if (!spec.description) throw new Error("createSkill: `description` is required.");
+  return {
+    name: spec.name,
+    description: spec.description,
+    source: `inline://${spec.name}`,
+    instructions: spec.instructions,
+    ...spec.category !== void 0 ? { category: spec.category } : {},
+    ...spec.dependencies !== void 0 ? { dependencies: spec.dependencies } : {}
+  };
+}
+
 // src/cron.ts
 init_errors();
 
@@ -20127,6 +20176,53 @@ function createPermissionPlugin(engine, opts = {}) {
   });
 }
 
+// src/schema-normalizer.ts
+init_to_json_schema();
+function isJsonSchemaObject(s) {
+  if (typeof s !== "object" || s === null) return false;
+  const o = s;
+  if ("$schema" in o) return true;
+  return o.type === "object" && typeof o.properties === "object" && o.properties !== null;
+}
+function hasToJsonSchemaMethod(s) {
+  return typeof s === "object" && s !== null && typeof s.toJsonSchema === "function";
+}
+function isZodSchema(s) {
+  if (typeof s !== "object" || s === null) return false;
+  const o = s;
+  return typeof o.safeParse === "function" && ("_def" in o || "def" in o);
+}
+function isValibotSchema(s) {
+  if (typeof s !== "object" || s === null) return false;
+  const o = s;
+  return o.kind === "schema" && "type" in o && typeof o.toJsonSchema !== "function";
+}
+async function normalizeSchema(schema) {
+  if (isJsonSchemaObject(schema)) return schema;
+  if (isValibotSchema(schema)) {
+    const specifier = "@valibot/to-json-schema";
+    try {
+      const mod = await import(specifier);
+      return mod.toJsonSchema(schema);
+    } catch (err) {
+      const missing = err instanceof Error && /Cannot find|Cannot resolve|ERR_MODULE_NOT_FOUND/.test(err.message);
+      if (missing) {
+        throw new Error(
+          "normalizeSchema: a Valibot schema requires the optional '@valibot/to-json-schema' package. Install it, or use a Zod schema (the default recommendation)."
+        );
+      }
+      throw err;
+    }
+  }
+  if (isZodSchema(schema)) {
+    return toJsonSchema(schema, { unrepresentable: "any" });
+  }
+  if (hasToJsonSchemaMethod(schema)) return schema.toJsonSchema();
+  throw new Error(
+    "normalizeSchema: unsupported schema. Supported: Zod (default), JSON Schema, ArkType (.toJsonSchema()), Valibot (with @valibot/to-json-schema)."
+  );
+}
+
 // src/security.ts
 init_security();
 var Security = class {
@@ -20925,6 +21021,7 @@ exports.createAgentFactory = createAgentFactory;
 exports.createCounterBudgetTracker = createCounterBudgetTracker;
 exports.createNoopMemoryProvider = createNoopMemoryProvider;
 exports.createPermissionPlugin = createPermissionPlugin;
+exports.createSkill = createSkill;
 exports.createSquad = createSquad;
 exports.definePlugin = definePlugin;
 exports.defineProvider = defineProvider;
@@ -20935,6 +21032,7 @@ exports.inferApiMode = inferApiMode;
 exports.isTransientError = isTransientError;
 exports.migrateSqliteToLance = migrateSqliteToLance2;
 exports.mkMemoryId = mkMemoryId;
+exports.normalizeSchema = normalizeSchema;
 exports.normalizeUsage = normalizeUsage;
 exports.preflightCheck = preflightCheck;
 exports.scopedConversationId = scopedConversationId;