@lazyingart/agintiflow 0.20.144 → 0.20.145

package/docs/skills-and-tools.md

@@ -71,3 +71,10 @@ For substantial writing tasks, prefer:
 - The main agent for all non-writing work around that draft: file names, workspace edits, citations, Markdown/LaTeX/Final Draft formatting, PDF compilation, canvas publishing, and verification.
 
 The writer receives only writing context: brief, canon, style guide, prior draft, target, audience, constraints, length, and downstream format intent. It should not receive shell/file/browser policy or agent-runtime details.
+
+For schema-bound structured data, prefer:
+
+- `json_specialist` for one isolated extraction, annotation, conversion, or validation request.
+- `json_specialist_batch` for independent chunks that can be requested in parallel without shared writes.
+
+The JSON specialist receives only the task, focused instructions, minimal context, input, and JSON Schema. It tries provider-native structured output (`json_schema` or JSON object mode) when available, then falls back to prompt-and-validate parsing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.144",
+  "version": "0.20.145",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",

package/scripts/smoke-coding-tools.js

@@ -25,6 +25,7 @@ import { createPlan } from "../src/model-client.js";
 import { selectModelRoute } from "../src/model-routing.js";
 import { listParallelScouts, runParallelScouts, shouldRunParallelScouts } from "../src/parallel-scouts.js";
 import { buildFailedCommandAdvice, buildPermissionAdvice } from "../src/permission-advice.js";
+import { runJsonSpecialist } from "../src/json-specialist.js";
 import { SessionStore } from "../src/session-store.js";
 import { getTaskProfile } from "../src/task-profiles.js";
 import { searchWeb } from "../src/web-search.js";
@@ -613,6 +614,30 @@ try {
     writingRun.events.some((event) => event.type === "tool.completed" && event.data?.toolName === "writing_specialist"),
     "mock agent did not route writing work through writing_specialist"
   );
+  const jsonResult = await runJsonSpecialist(
+    {
+      task: "Return a strict JSON status object.",
+      schema: {
+        type: "object",
+        properties: {
+          summary: { type: "string" },
+          complete: { type: "boolean" },
+        },
+        required: ["summary", "complete"],
+        additionalProperties: false,
+      },
+      inputText: "structured JSON smoke",
+      provider: "mock",
+    },
+    { provider: "mock", model: "mock-agent" },
+    new SessionStore(runtimeDir, "json-specialist-smoke", { projectRoot: workspace, commandCwd: workspace })
+  );
+  assert(jsonResult.ok && jsonResult.result?.complete === true, "json_specialist mock result did not satisfy schema");
+  const jsonRun = await runMock("Extract a valid JSON object with schema from this text.", "coding-json-specialist");
+  assert(
+    jsonRun.events.some((event) => event.type === "tool.completed" && event.data?.toolName === "json_specialist"),
+    "mock agent did not route structured JSON work through json_specialist"
+  );
 
   await fs.mkdir(path.join(workspace, "src"), { recursive: true });
   await fs.mkdir(path.join(workspace, "test"), { recursive: true });
@@ -1104,6 +1129,8 @@ try {
           "deepseek_pro_writing_route",
           "writing_specialist_mock",
           "writing_specialist_mock_routing",
+          "json_specialist_mock",
+          "json_specialist_mock_routing",
           "runtime_time_context",
           "large_profile_pro_route",
           "auto_system_pro_route",

package/skills/structured-json/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: structured-json
+description: Use isolated schema-bound JSON generation for extraction, annotation, conversion, classification, or chunked data production without mixing in agent runtime context.
+---
+
+# Structured JSON
+
+Use this skill when the user needs reliable JSON that follows an explicit schema, especially for repetitive chunk processing.
+
+## Workflow
+
+1. Define the smallest useful JSON Schema for the next data artifact.
+2. Pass only the task, focused instructions, minimal domain context, input, and schema to `json_specialist`.
+3. Use `json_specialist_batch` only when items are independent and can be processed in parallel without shared writes.
+4. Keep formatting, file writes, validation scripts, compilation, and project-specific orchestration in the main agent.
+5. After the tool returns, validate any project-specific invariants with local scripts before treating the data as complete.
+
+## Boundaries
+
+- Do not pass shell, browser, file policy, package-install, or agent-planning context into the JSON specialist.
+- Do not make schemas book-, app-, or project-specific inside AgInTiFlow core. Project schemas belong in the target repository.
+- Prefer provider-native structured output when available, but keep fallback parsing enabled unless the user explicitly wants hard failure on unsupported response formats.

package/src/agent-runner.js

@@ -26,6 +26,7 @@ import {
 import { refreshCodebaseMap } from "./codebase-map.js";
 import { readImage, researchWrapper, webResearch } from "./perception-tools.js";
 import { searchWeb } from "./web-search.js";
+import { runJsonSpecialist, runJsonSpecialistBatch } from "./json-specialist.js";
 import { runWritingSpecialist } from "./writing-specialist.js";
 import { runParallelScouts, shouldRunParallelScouts } from "./parallel-scouts.js";
 import { readProjectInstructions } from "./project.js";
@@ -1214,6 +1215,26 @@ function sanitizeToolArgs(toolName, args) {
         typeof args.constraints === "string" ? `[${Buffer.byteLength(args.constraints, "utf8")} bytes sha256=${hashForLog(args.constraints)}]` : safeArgs.constraints,
     };
   }
+  if (toolName === "json_specialist") {
+    return {
+      ...safeArgs,
+      task: typeof args.task === "string" ? `[${Buffer.byteLength(args.task, "utf8")} bytes sha256=${hashForLog(args.task)}]` : safeArgs.task,
+      instructions:
+        typeof args.instructions === "string" ? `[${Buffer.byteLength(args.instructions, "utf8")} bytes sha256=${hashForLog(args.instructions)}]` : safeArgs.instructions,
+      context: typeof args.context === "string" ? `[${Buffer.byteLength(args.context, "utf8")} bytes sha256=${hashForLog(args.context)}]` : safeArgs.context,
+      inputText:
+        typeof args.inputText === "string" ? `[${Buffer.byteLength(args.inputText, "utf8")} bytes sha256=${hashForLog(args.inputText)}]` : safeArgs.inputText,
+      schemaJson:
+        typeof args.schemaJson === "string" ? `[${Buffer.byteLength(args.schemaJson, "utf8")} bytes sha256=${hashForLog(args.schemaJson)}]` : safeArgs.schemaJson,
+    };
+  }
+  if (toolName === "json_specialist_batch") {
+    return {
+      ...safeArgs,
+      defaults: args.defaults ? "[json specialist defaults redacted]" : safeArgs.defaults,
+      items: Array.isArray(args.items) ? `[${args.items.length} json specialist items]` : safeArgs.items,
+    };
+  }
   if (toolName === "apply_patch") {
     return {
       ...safeArgs,
@@ -1309,6 +1330,19 @@ export function sanitizeToolResult(result) {
     safeResult.draftTruncated = true;
     delete safeResult.draft;
   }
+  if (safeResult.toolName === "json_specialist" && safeResult.result !== undefined) {
+    const encoded = JSON.stringify(safeResult.result);
+    safeResult.resultBytes = Buffer.byteLength(encoded, "utf8");
+    if (safeResult.resultBytes > TOOL_RESULT_INLINE_CONTENT_BYTES) {
+      safeResult.resultPreview = encoded.slice(0, TOOL_RESULT_CONTENT_PREVIEW_CHARS);
+      safeResult.resultTruncated = true;
+      delete safeResult.result;
+    }
+  }
+  if (safeResult.toolName === "json_specialist_batch" && Array.isArray(safeResult.results)) {
+    safeResult.resultCount = safeResult.results.length;
+    safeResult.results = safeResult.results.map((item) => sanitizeToolResult(item));
+  }
   return safeResult;
 }
 
@@ -1584,6 +1618,20 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
         return result;
       }
+      case "json_specialist": {
+        const result = await runJsonSpecialist(args, config, store);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
+      case "json_specialist_batch": {
+        const result = await runJsonSpecialistBatch(args.items || [], { ...args, items: undefined }, config, store);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
       case "writing_specialist": {
         const result = await runWritingSpecialist(args, config, store);
         const eventResult = sanitizeToolResult(result);

package/src/guardrails.js

@@ -304,6 +304,66 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
     return { allowed: true };
   }
 
+  if (toolName === "json_specialist") {
+    const task = String(args.task || args.prompt || "").trim();
+    if (!task) return { allowed: false, reason: "JSON specialist requires task.", category: "json-specialist" };
+    if (!args.schema && !String(args.schemaJson || "").trim()) {
+      return { allowed: false, reason: "JSON specialist requires schema or schemaJson.", category: "json-specialist" };
+    }
+    const provider = String(args.provider || process.env.AGINTI_JSON_PROVIDER || "").trim();
+    if (provider && !["deepseek", "openai", "qwen", "venice", "mock"].includes(provider)) {
+      return { allowed: false, reason: `Unknown JSON specialist provider: ${provider}`, category: "json-specialist" };
+    }
+    const payloadBytes = Buffer.byteLength(
+      [
+        task,
+        args.instructions,
+        args.requirements,
+        args.context,
+        args.inputText,
+        args.source,
+        args.content,
+        args.schemaJson,
+        args.inputJson ? JSON.stringify(args.inputJson) : "",
+        args.schema ? JSON.stringify(args.schema) : "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+      "utf8"
+    );
+    if (payloadBytes > 220_000) {
+      return {
+        allowed: false,
+        reason: "JSON specialist payload is too large. Split the source into smaller independent items or save inputs to files and pass a focused excerpt.",
+        category: "json-specialist",
+      };
+    }
+    return { allowed: true };
+  }
+
+  if (toolName === "json_specialist_batch") {
+    const items = Array.isArray(args.items) ? args.items : [];
+    if (items.length === 0) return { allowed: false, reason: "JSON specialist batch requires items.", category: "json-specialist" };
+    if (items.length > 32) return { allowed: false, reason: "JSON specialist batch is limited to 32 items per tool call.", category: "json-specialist" };
+    const concurrency = Number(args.concurrency || 4);
+    if (Number.isFinite(concurrency) && concurrency > 16) {
+      return { allowed: false, reason: "JSON specialist batch concurrency is limited to 16.", category: "json-specialist" };
+    }
+    const provider = String(args.provider || args.defaults?.provider || process.env.AGINTI_JSON_PROVIDER || "").trim();
+    if (provider && !["deepseek", "openai", "qwen", "venice", "mock"].includes(provider)) {
+      return { allowed: false, reason: `Unknown JSON specialist provider: ${provider}`, category: "json-specialist" };
+    }
+    const payloadBytes = Buffer.byteLength(JSON.stringify({ defaults: args.defaults || {}, items }), "utf8");
+    if (payloadBytes > 360_000) {
+      return {
+        allowed: false,
+        reason: "JSON specialist batch payload is too large. Use fewer items or smaller chunk text per call.",
+        category: "json-specialist",
+      };
+    }
+    return { allowed: true };
+  }
+
   if (toolName === "generate_image") {
     if (!config.allowAuxiliaryTools) {
       return { allowed: false, reason: "Auxiliary tools are disabled for this run.", category: "auxiliary-tools" };

package/src/json-specialist.js

@@ -0,0 +1,422 @@
+import crypto from "node:crypto";
+import { createChatCompletion, createClient } from "./model-client.js";
+import { getProviderDefaults } from "./model-routing.js";
+import { redactSensitiveText, redactValue } from "./redaction.js";
+
+const MAX_INLINE_PREVIEW = 1600;
+const JSON_PROVIDERS = new Set(["openai", "deepseek", "qwen", "venice", "mock"]);
+
+function compact(value = "", limit = MAX_INLINE_PREVIEW) {
+  const text = redactSensitiveText(String(value || "").trim());
+  if (text.length <= limit) return text;
+  return `${text.slice(0, Math.max(0, limit - 24))} ... [truncated]`;
+}
+
+function parseJsonValue(content = "") {
+  const text = String(content || "").trim();
+  if (!text) return { ok: false, error: "empty JSON response" };
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidates = [fenced?.[1], text].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      return { ok: true, value: JSON.parse(candidate.trim()) };
+    } catch {
+      // Try a balanced excerpt below.
+    }
+    const starts = ["{", "["]
+      .map((char) => ({ char, index: candidate.indexOf(char) }))
+      .filter((item) => item.index >= 0)
+      .sort((a, b) => a.index - b.index);
+    for (const start of starts) {
+      const close = start.char === "{" ? "}" : "]";
+      const end = candidate.lastIndexOf(close);
+      if (end <= start.index) continue;
+      try {
+        return { ok: true, value: JSON.parse(candidate.slice(start.index, end + 1)) };
+      } catch {
+        // Keep looking.
+      }
+    }
+  }
+  return { ok: false, error: "response was not parseable JSON" };
+}
+
+function normalizeSchema(raw) {
+  let schema = raw;
+  let name = "";
+  let strict = true;
+  if (typeof schema === "string" && schema.trim()) {
+    schema = JSON.parse(schema);
+  }
+  if (schema?.schema && typeof schema.schema === "object" && !schema.type) {
+    name = String(schema.name || "").trim();
+    strict = schema.strict !== false;
+    schema = schema.schema;
+  }
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error("JSON specialist requires a JSON Schema object.");
+  }
+  return { schema, name, strict };
+}
+
+function normalizeInputValue(args = {}) {
+  if (args.inputJson !== undefined) return redactValue(args.inputJson);
+  if (args.input !== undefined) return redactValue(args.input);
+  const text = args.inputText ?? args.source ?? args.content ?? "";
+  return redactSensitiveText(String(text || ""));
+}
+
+function normalizeResponseFormat(value = "") {
+  const normalized = String(value || "auto").trim().toLowerCase();
+  if (["auto", "json_schema", "json_object", "prompt"].includes(normalized)) return normalized;
+  return "auto";
+}
+
+function normalizeJsonRequest(args = {}) {
+  const normalizedSchema = normalizeSchema(args.schemaJson || args.schema);
+  const task = redactSensitiveText(String(args.task || args.prompt || "").trim());
+  const instructions = redactSensitiveText(String(args.instructions || args.requirements || "").trim());
+  const context = redactSensitiveText(String(args.context || "").trim());
+  const temperature = Number.isFinite(Number(args.temperature)) ? Math.min(Math.max(Number(args.temperature), 0), 1.2) : 0;
+  const maxTokens = Number.isFinite(Number(args.maxTokens)) ? Math.max(256, Math.floor(Number(args.maxTokens))) : 4096;
+  const provider = String(args.provider || process.env.AGINTI_JSON_PROVIDER || "").trim();
+  const model = String(args.model || process.env.AGINTI_JSON_MODEL || "").trim();
+  const schemaName = String(args.schemaName || normalizedSchema.name || "aginti_structured_output")
+    .trim()
+    .replace(/[^A-Za-z0-9_-]/g, "_")
+    .slice(0, 64) || "aginti_structured_output";
+  return {
+    task,
+    instructions,
+    context,
+    input: normalizeInputValue(args),
+    schema: normalizedSchema.schema,
+    schemaName,
+    strict: args.strict === undefined ? normalizedSchema.strict : args.strict !== false,
+    responseFormat: normalizeResponseFormat(args.responseFormat),
+    fallbackOnInvalid: args.fallbackOnInvalid !== false,
+    temperature,
+    maxTokens,
+    provider,
+    model,
+  };
+}
+
+function jsonSystemPrompt() {
+  return [
+    "You are the isolated AgInTiFlow JSON Specialist.",
+    "You transform only the supplied task, input, and schema into structured JSON.",
+    "You do not know or discuss AgInTiFlow internals, shell tools, browser tools, file policies, planning, package installs, or execution constraints.",
+    "Never include commentary, markdown fences, prose explanations, or partial objects.",
+    "Return one JSON value that satisfies the provided schema.",
+  ].join(" ");
+}
+
+function jsonUserPrompt(request, attempt) {
+  return JSON.stringify(
+    {
+      boundary:
+        "This is the complete context visible to the JSON specialist. Ignore absent agent/runtime details. Produce only schema-valid JSON.",
+      task: request.task,
+      instructions: request.instructions,
+      context: request.context,
+      input: request.input,
+      json_schema: request.schema,
+      output_contract: {
+        mode: attempt,
+        strict: request.strict,
+        requirement: "Return exactly one JSON value matching json_schema. Do not wrap it in markdown.",
+      },
+    },
+    null,
+    2
+  );
+}
+
+function allowedTypes(schema) {
+  if (!schema || schema.type === undefined) return [];
+  return Array.isArray(schema.type) ? schema.type : [schema.type];
+}
+
+function typeMatches(value, type) {
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return value && typeof value === "object" && !Array.isArray(value);
+  if (type === "integer") return Number.isInteger(value);
+  if (type === "number") return typeof value === "number" && Number.isFinite(value);
+  if (type === "string") return typeof value === "string";
+  if (type === "boolean") return typeof value === "boolean";
+  if (type === "null") return value === null;
+  return true;
+}
+
+function validateSchema(value, schema, path = "$") {
+  if (!schema || typeof schema !== "object") return [];
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length > 0) {
+    const variants = schema.anyOf.map((variant) => validateSchema(value, variant, path));
+    return variants.some((errs) => errs.length === 0) ? [] : [`${path}: did not match anyOf`];
+  }
+  if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) {
+    const matches = schema.oneOf.filter((variant) => validateSchema(value, variant, path).length === 0).length;
+    return matches === 1 ? [] : [`${path}: did not match exactly one oneOf variant`];
+  }
+  const errors = [];
+  if (schema.const !== undefined && JSON.stringify(value) !== JSON.stringify(schema.const)) {
+    errors.push(`${path}: expected const ${JSON.stringify(schema.const)}`);
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((item) => JSON.stringify(item) === JSON.stringify(value))) {
+    errors.push(`${path}: value is not in enum`);
+  }
+  const types = allowedTypes(schema);
+  if (types.length > 0 && !types.some((type) => typeMatches(value, type))) {
+    errors.push(`${path}: expected type ${types.join("|")}`);
+    return errors;
+  }
+  if (Array.isArray(value)) {
+    if (Number.isFinite(schema.minItems) && value.length < schema.minItems) errors.push(`${path}: fewer than minItems`);
+    if (Number.isFinite(schema.maxItems) && value.length > schema.maxItems) errors.push(`${path}: more than maxItems`);
+    if (schema.items) {
+      value.forEach((item, index) => errors.push(...validateSchema(item, schema.items, `${path}[${index}]`)));
+    }
+  } else if (value && typeof value === "object") {
+    const properties = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+    for (const key of schema.required || []) {
+      if (!(key in value)) errors.push(`${path}.${key}: required property missing`);
+    }
+    for (const [key, child] of Object.entries(properties)) {
+      if (key in value) errors.push(...validateSchema(value[key], child, `${path}.${key}`));
+    }
+    if (schema.additionalProperties === false) {
+      for (const key of Object.keys(value)) {
+        if (!(key in properties)) errors.push(`${path}.${key}: additional property not allowed`);
+      }
+    }
+  }
+  return errors;
+}
+
+function mockValueForSchema(schema) {
+  if (!schema || typeof schema !== "object") return {};
+  if (schema.const !== undefined) return schema.const;
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
+  const type = allowedTypes(schema)[0] || (schema.properties ? "object" : "string");
+  if (type === "string") return "mock";
+  if (type === "integer") return 1;
+  if (type === "number") return 1;
+  if (type === "boolean") return true;
+  if (type === "null") return null;
+  if (type === "array") {
+    const count = Number.isFinite(schema.minItems) ? Math.max(1, schema.minItems) : 1;
+    return Array.from({ length: count }, () => mockValueForSchema(schema.items || { type: "string" }));
+  }
+  const result = {};
+  const properties = schema.properties && typeof schema.properties === "object" ? schema.properties : {};
+  const keys = new Set([...(schema.required || []), ...Object.keys(properties).slice(0, 6)]);
+  for (const key of keys) result[key] = mockValueForSchema(properties[key] || { type: "string" });
+  return result;
+}
+
+function attemptsForRequest(request, provider) {
+  if (request.responseFormat === "prompt") return ["prompt"];
+  if (request.responseFormat === "json_schema") return ["json_schema", "prompt"];
+  if (request.responseFormat === "json_object") return ["json_object", "prompt"];
+  if (["openai", "deepseek", "qwen"].includes(provider)) return ["json_schema", "json_object", "prompt"];
+  return ["json_object", "prompt"];
+}
+
+function responseFormatForAttempt(request, attempt) {
+  if (attempt === "json_schema") {
+    return {
+      type: "json_schema",
+      json_schema: {
+        name: request.schemaName,
+        strict: request.strict,
+        schema: request.schema,
+      },
+    };
+  }
+  if (attempt === "json_object") return { type: "json_object" };
+  return null;
+}
+
+function errorLooksLikeUnsupportedResponseFormat(error) {
+  const message = [error?.message, error?.error?.message, error?.response?.data?.error?.message]
+    .filter(Boolean)
+    .join(" ");
+  return /response_format|json_schema|json_object|unsupported|invalid request|400/i.test(message);
+}
+
+function parsedRawPreview(rawContent = "") {
+  return rawContent ? compact(rawContent, 1200) : "";
+}
+
+export async function runJsonSpecialist(args = {}, config = {}, store = null) {
+  let request;
+  try {
+    request = normalizeJsonRequest(args);
+  } catch (error) {
+    return {
+      ok: false,
+      toolName: "json_specialist",
+      reason: redactSensitiveText(error instanceof Error ? error.message : String(error)),
+    };
+  }
+  if (!request.task) {
+    return {
+      ok: false,
+      toolName: "json_specialist",
+      reason: "task is required.",
+    };
+  }
+
+  const startedAt = new Date().toISOString();
+  const requestFingerprint = crypto.createHash("sha256").update(JSON.stringify(redactValue(request))).digest("hex");
+  let model = request.model || config.model || "";
+  let provider = request.provider || config.provider || "";
+  let rawContent = "";
+  const attemptNotes = [];
+
+  try {
+    let result;
+    let validationErrors = [];
+    let usedResponseFormat = "mock";
+    if (config.provider === "mock" || provider === "mock") {
+      provider = "mock";
+      model = request.model || config.model || "mock-agent";
+      result = mockValueForSchema(request.schema);
+      validationErrors = validateSchema(result, request.schema);
+    } else {
+      if (provider && !JSON_PROVIDERS.has(provider)) {
+        throw new Error(`Unknown JSON specialist provider: ${provider}`);
+      }
+      const providerDefaults = request.provider ? getProviderDefaults(request.provider) : {};
+      const jsonConfig = {
+        ...config,
+        ...providerDefaults,
+        provider: provider || config.provider,
+        model: model || providerDefaults.model || config.model,
+      };
+      model = jsonConfig.model;
+      provider = jsonConfig.provider;
+      const client = createClient(jsonConfig);
+      const attempts = attemptsForRequest(request, provider);
+      for (const attempt of attempts) {
+        const responseFormat = responseFormatForAttempt(request, attempt);
+        const payload = {
+          model: jsonConfig.model,
+          temperature: request.temperature,
+          max_tokens: request.maxTokens,
+          messages: [
+            { role: "system", content: jsonSystemPrompt() },
+            { role: "user", content: jsonUserPrompt(request, attempt) },
+          ],
+          ...(responseFormat ? { response_format: responseFormat } : {}),
+        };
+        try {
+          const response = await createChatCompletion(client, payload, jsonConfig, `json specialist ${attempt} request`);
+          rawContent = response.choices[0]?.message?.content || "";
+          const parsed = parseJsonValue(rawContent);
+          if (!parsed.ok) {
+            attemptNotes.push(`${attempt}: ${parsed.error}`);
+            if (request.fallbackOnInvalid && attempt !== attempts.at(-1)) continue;
+            throw new Error(parsed.error);
+          }
+          const errors = validateSchema(parsed.value, request.schema);
+          if (errors.length > 0) {
+            attemptNotes.push(`${attempt}: ${errors.slice(0, 4).join("; ")}`);
+            if (request.fallbackOnInvalid && attempt !== attempts.at(-1)) continue;
+          }
+          result = parsed.value;
+          validationErrors = errors;
+          usedResponseFormat = attempt;
+          break;
+        } catch (error) {
+          const message = redactSensitiveText(error instanceof Error ? error.message : String(error));
+          attemptNotes.push(`${attempt}: ${message}`);
+          if (attempt !== attempts.at(-1) && (request.fallbackOnInvalid || errorLooksLikeUnsupportedResponseFormat(error))) continue;
+          throw error;
+        }
+      }
+    }
+
+    const artifact = {
+      version: 1,
+      generatedAt: new Date().toISOString(),
+      startedAt,
+      provider,
+      model,
+      responseFormat: usedResponseFormat,
+      requestFingerprint,
+      request: redactValue(request),
+      result: redactValue(result),
+      validationErrors,
+      attemptNotes,
+      rawPreview: parsedRawPreview(rawContent),
+    };
+    const artifactPath = store
+      ? await store.saveJsonArtifact(`json-specialist-${Date.now()}.json`, artifact).catch(() => "")
+      : "";
+    return {
+      ok: validationErrors.length === 0,
+      toolName: "json_specialist",
+      provider,
+      model,
+      responseFormat: usedResponseFormat,
+      args: {
+        task: request.task,
+        schemaName: request.schemaName,
+        responseFormat: request.responseFormat,
+        provider: request.provider,
+        requestFingerprint,
+      },
+      artifactPath,
+      result,
+      validationErrors,
+      attemptNotes,
+      rawPreview: parsedRawPreview(rawContent),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      toolName: "json_specialist",
+      provider,
+      model,
+      args: {
+        task: request.task,
+        schemaName: request.schemaName,
+        responseFormat: request.responseFormat,
+        provider: request.provider,
+        requestFingerprint,
+      },
+      error: redactSensitiveText(error instanceof Error ? error.message : String(error)),
+      attemptNotes,
+      rawPreview: parsedRawPreview(rawContent),
+    };
+  }
+}
+
+export async function runJsonSpecialistBatch(tasks = [], options = {}, config = {}, store = null) {
+  const items = Array.isArray(tasks) ? tasks : [];
+  const concurrency = Math.min(Math.max(Number(options.concurrency) || 4, 1), 32);
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const task = items[index] || {};
+      results[index] = await runJsonSpecialist({ ...options.defaults, ...task }, config, store);
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+  return {
+    ok: results.every((item) => item?.ok),
+    toolName: "json_specialist_batch",
+    count: results.length,
+    succeeded: results.filter((item) => item?.ok).length,
+    failed: results.filter((item) => !item?.ok).length,
+    concurrency,
+    results,
+  };
+}

package/src/model-client.js

@@ -567,6 +567,27 @@ function mockWritingSpecialistToolForGoal(goal = "", taskProfile = "") {
   });
 }
 
+function mockJsonSpecialistToolForGoal(goal = "") {
+  const text = String(goal || "");
+  if (!/\b(json|schema|structured output|extract structured|valid object|valid array)\b/i.test(text)) return null;
+  return mockToolCall("json_specialist", {
+    task: text.replace(/\s+/g, " ").slice(0, 800) || "Return structured JSON.",
+    schemaName: "mock_structured_output",
+    schema: {
+      type: "object",
+      properties: {
+        summary: { type: "string" },
+        complete: { type: "boolean" },
+      },
+      required: ["summary", "complete"],
+      additionalProperties: false,
+    },
+    inputText: text.slice(0, 1200),
+    responseFormat: "prompt",
+    provider: "mock",
+  });
+}
+
 function mockPreviewToolForGoal(goal = "") {
   const text = String(goal).toLowerCase();
   if (!/(open|preview|view|browser|website|web\s*site)/.test(text)) return null;
@@ -676,6 +697,7 @@ export async function createPlan(client, config, state) {
             ? "web_search is available for lightweight snippets. web_research is available for auditable sourced research with persisted artifacts; use mode=snippets by default and mode=openai only when hosted OpenAI web research is needed and configured. Prefer these tools over opening a search engine in the browser."
             : "web_search is disabled for this run.",
           "For substantial writing work such as novels, chapters, books, scripts, essays, LaTeX manuscripts, or research-paper prose, plan to call writing_specialist with only the writing brief/canon/style/draft context. The main agent should handle files, citations, checks, and Markdown/LaTeX/Final Draft formatting after the isolated writing draft returns.",
+          "For repetitive schema-bound extraction, annotation, conversion, or validation tasks, use json_specialist with only the task, input, schema, and focused instructions. It calls the model directly for strict JSON, tries provider-native structured output when supported, and keeps agent/runtime/tool context out of the specialist prompt.",
           config.allowFileTools
             ? "read_image is available for workspace-local or allowed remote screenshots/images using OpenAI vision when OPENAI_API_KEY is configured. It returns typed visual observations and persists a perception artifact; if credentials are missing, report the blocker instead of guessing from the filename."
             : "",
@@ -729,6 +751,66 @@ export async function requestNextStep(client, config, messages) {
         },
       },
     },
+    {
+      type: "function",
+      function: {
+        name: "json_specialist",
+        description:
+          "Call an isolated schema-only LLM context for strict JSON extraction, annotation, classification, conversion, or validation. Pass only the task, input, schema, and focused instructions; do not pass shell/browser/file policy, agent runtime, or broad planning context. The tool tries provider-native structured JSON where supported and falls back to prompt-and-validate parsing.",
+        parameters: {
+          type: "object",
+          properties: {
+            task: { type: "string", description: "Focused JSON task. Required." },
+            instructions: { type: "string", description: "Additional schema-specific rules or quality constraints." },
+            context: { type: "string", description: "Minimal domain context needed for the JSON transformation." },
+            inputText: { type: "string", description: "Source text or serialized input to transform." },
+            inputJson: { type: "object", description: "Source object to transform.", additionalProperties: true },
+            schema: { type: "object", description: "JSON Schema object for the expected output.", additionalProperties: true },
+            schemaJson: { type: "string", description: "JSON-stringified schema alternative when schema is easier to pass as text." },
+            schemaName: { type: "string", description: "Short schema name for provider-native structured output." },
+            responseFormat: {
+              type: "string",
+              enum: ["auto", "json_schema", "json_object", "prompt"],
+              description: "Native structured-output preference. auto tries native JSON schema/object then prompt fallback.",
+            },
+            fallbackOnInvalid: { type: "boolean", description: "Try a weaker fallback if native structured output is unsupported or invalid. Defaults true." },
+            strict: { type: "boolean", description: "Use strict provider schema mode where supported. Defaults true." },
+            temperature: { type: "number", description: "Defaults to 0 for deterministic structured data." },
+            maxTokens: { type: "integer", description: "Maximum completion tokens for the JSON specialist call." },
+            provider: {
+              type: "string",
+              enum: ["deepseek", "openai", "qwen", "venice", "mock"],
+              description: "Optional provider override. Defaults to AGINTI_JSON_PROVIDER or current provider.",
+            },
+            model: { type: "string", description: "Optional model override. Defaults to AGINTI_JSON_MODEL or current model." },
+          },
+          required: ["task"],
+          additionalProperties: false,
+        },
+      },
+    },
+    {
+      type: "function",
+      function: {
+        name: "json_specialist_batch",
+        description:
+          "Run many isolated json_specialist requests concurrently for chunked structured-data work. Each item is one independent schema-bound task. Use only for independent items with no shared writes or ordering dependency.",
+        parameters: {
+          type: "object",
+          properties: {
+            concurrency: { type: "integer", description: "Parallel request count, clamped by runtime guardrails." },
+            defaults: { type: "object", description: "Default json_specialist arguments applied to every item.", additionalProperties: true },
+            items: {
+              type: "array",
+              description: "Independent json_specialist argument objects.",
+              items: { type: "object", additionalProperties: true },
+            },
+          },
+          required: ["items"],
+          additionalProperties: false,
+        },
+      },
+    },
     {
       type: "function",
       function: {
@@ -1393,6 +1475,11 @@ export async function requestNextStep(client, config, messages) {
       }
     }
 
+    const jsonTool = mockJsonSpecialistToolForGoal(config.goal);
+    if (jsonTool) {
+      return mockChatResponse("Mock mode will exercise the isolated JSON specialist.", [jsonTool]);
+    }
+
     const writingTool = mockWritingSpecialistToolForGoal(config.goal, config.taskProfile);
     if (writingTool) {
       return mockChatResponse("Mock mode will exercise the isolated writing specialist before file or format work.", [writingTool]);

package/src/step-budget-controller.js

@@ -6,6 +6,8 @@ const PROGRESS_TOOL_NAMES = new Set([
   "apply_patch",
   "generate_image",
   "inspect_project",
+  "json_specialist",
+  "json_specialist_batch",
   "open_workspace_file",
   "preview_workspace",
   "read_file",