@theokit/sdk 2.18.1 → 2.20.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.20.0
+
+### Minor Changes
+
+- **M21 — `GenerateObjectOptions.structuringModel`.** An optional separate model for the structured-extraction step: when set, `model` first produces a free-text reasoned answer (phase 1), then `structuringModel` extracts the schema-matched object by calling the synthetic `output` tool over that answer (phase 2). Lets a large model reason while a cheap fast model structures. Absent ⇒ today's single-model flow (backward-compatible). Proven by a golden test asserting two distinct model ids in the run.
+- **M22 — `createSkill()` + `SkillsSettings.skillsDir` / `.inline`.** `createSkill({ name, description, instructions })` defines a skill in TypeScript without a `SKILL.md` file; pass code-defined skills via `skills.inline` (they surface in `list()` + the `<skills>` block alongside filesystem skills, overriding a file skill of the same name). `skills.skillsDir` discovers skills from a custom directory instead of `<cwd>/.theokit/skills`. Both compose with the per-request enabled-name resolver.
+- **M23 — `normalizeSchema()`.** Converts a schema from Zod (default), JSON Schema (passthrough), ArkType (`.toJsonSchema()`), or Valibot (via the optional `@valibot/to-json-schema` peer) to the internal JSON Schema the synthetic `output` tool uses. Zod stays the default and the documented recommendation; thin adapter, uniform parse-failure handling. A golden test per provider.
+
+## 2.19.0
+
+### Minor Changes
+
+- `GenerateObjectOptions.errorStrategy` (`"throw" | "return-partial" | "return-raw"`, default `"throw"`) — controls what `Agent.generateObject` does when the model's output still fails schema validation after all retries. `"return-raw"` resolves with the raw unvalidated input; `"return-partial"` salvages best-effort (object schemas keep only fields that individually validate). Additive + backward-compatible (M14).
+
 ## 2.18.1
 
 ### Patch Changes

package/dist/a2a/index.cjs

@@ -6807,23 +6807,27 @@ var init_skills_manager = __esm({
   "src/internal/runtime/skills/skills-manager.ts"() {
     init_discover_skills();
     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}
@@ -6831,6 +6835,13 @@ var init_skills_manager = __esm({
             );
           }
         });
+        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);
@@ -6877,7 +6888,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() };
@@ -7863,22 +7877,23 @@ async function executeTool(inputs, resolved, call) {
     return { stdout: "", stderr: `Unknown tool ${call.name}`, exitCode: 127 };
   }
   if (resolved.origin === "shell") return runShellTool(inputs, call);
-  if (resolved.origin === "memory") return runMemoryTool(resolved, call);
-  if (resolved.origin === "custom") return runCustomTool(resolved, call, inputs.signal);
+  if (resolved.origin === "memory") return runMemoryTool(resolved, call, inputs.context);
+  if (resolved.origin === "custom")
+    return runCustomTool(resolved, call, inputs.signal, inputs.context);
   return runMcpTool(inputs, resolved, call);
 }
-async function runMemoryTool(resolved, call) {
-  return runHandlerTool("memory", resolved.memoryHandler, call);
+async function runMemoryTool(resolved, call, context) {
+  return runHandlerTool("memory", resolved.memoryHandler, call, void 0, context);
 }
-async function runCustomTool(resolved, call, signal) {
-  return runHandlerTool("custom", resolved.customHandler, call, signal);
+async function runCustomTool(resolved, call, signal, context) {
+  return runHandlerTool("custom", resolved.customHandler, call, signal, context);
 }
-async function runHandlerTool(kind, handler, call, signal) {
+async function runHandlerTool(kind, handler, call, signal, context) {
   if (handler === void 0) {
     return { stdout: "", stderr: `${kind} tool ${call.name} has no handler`, exitCode: 127 };
   }
   try {
-    const stdout = await handler(call.input, { signal });
+    const stdout = await handler(call.input, { signal, context });
     return { stdout, stderr: "", exitCode: 0 };
   } catch (cause) {
     const message = cause instanceof Error ? cause.message : String(cause);
@@ -12383,6 +12398,9 @@ function buildLoopInputs(options, runId, userText) {
     // D318 — forward SendOptions.signal to the agent loop so streamLlmTurn
     // can attach it to the LLM `fetch({ signal })` call.
     ...options.sendOptions.signal !== void 0 ? { signal: options.sendOptions.signal } : {},
+    // M7 — forward SendOptions.context to the loop so every tool handler receives
+    // it on `ctx.context` (shared run config set once, e.g. projectRoot).
+    ...options.sendOptions.context !== void 0 ? { context: options.sendOptions.context } : {},
     // #58 / #57 — forward the per-tool timeout + tool-result guard so a consumer
     // can enable them via SendOptions (not only internal AgentLoopInputs).
     ...options.sendOptions.perToolTimeoutMs !== void 0 ? { perToolTimeoutMs: options.sendOptions.perToolTimeoutMs } : {},
@@ -17153,6 +17171,37 @@ __export(generate_object_exports, {
   GenerateObjectError: () => GenerateObjectError,
   generateObjectImpl: () => generateObjectImpl
 });
+function salvagePartial(schema, raw) {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const shape = schema.shape;
+  if (shape === void 0 || typeof shape !== "object") return raw;
+  const rawObj = raw;
+  const out = {};
+  for (const [key, fieldSchema] of Object.entries(shape)) {
+    if (typeof fieldSchema?.safeParse !== "function") continue;
+    const parsed = fieldSchema.safeParse(rawObj[key]);
+    if (parsed.success) out[key] = parsed.data;
+  }
+  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,
@@ -17175,8 +17224,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 } : {},
@@ -17185,7 +17237,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;
@@ -17219,6 +17271,22 @@ async function generateObjectImpl(options, deps) {
       }
       lastParseError = parsed.error;
     }
+    if (options.errorStrategy === "return-raw") {
+      return {
+        object: capturedRaw,
+        raw: capturedRaw,
+        usage: lastUsage,
+        finishReason: "tool_use"
+      };
+    }
+    if (options.errorStrategy === "return-partial") {
+      return {
+        object: salvagePartial(options.schema, capturedRaw),
+        raw: capturedRaw,
+        usage: lastUsage,
+        finishReason: "tool_use"
+      };
+    }
     throw new GenerateObjectError(
       "parse_failed",
       "Schema parse failed after all retries.",