@theokit/agents 0.46.0 → 1.0.0

package/dist/index.js

@@ -3,7 +3,6 @@ import {
   AgentDefinitionError,
   AgentRunner,
   AgentRunnerBuilder,
-  AgentWarningCode,
   BudgetExceededError,
   CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
@@ -14,12 +13,12 @@ import {
   agentsPlugin,
   buildModelSelection,
   compactionStrategyConfigSchema,
-  compileAgent,
   compileAgentDefinition,
   compileAgentModule,
   compileContextWindow,
   compileProjectContext,
   compileSkills,
+  compileSkillsSelection,
   compileTools,
   contextualTool,
   costGuard,
@@ -67,15 +66,430 @@ import {
   toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
-  unicodeNormalizer,
-  validateUniqueRoutes,
-  walkAgentMetadata
-} from "./chunk-YBNKD5UM.js";
-import "./chunk-NERDIS45.js";
+  unicodeNormalizer
+} from "./chunk-7KRJJX7W.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
 
+// src/capability/capability.ts
+import { isDeepStrictEqual } from "util";
+var CapabilityConflictError = class extends Error {
+  static {
+    __name(this, "CapabilityConflictError");
+  }
+  name = "CapabilityConflictError";
+  constructor(field, previous, next, capability) {
+    super(
+      // NUNCA ecoa os valores: um draft montado a partir de arquivo de config pode carregar
+      // token de MCP, header de auth, credencial de memória. Reporta a FORMA, como a validação
+      // de fronteira das capabilities já faz.
+      `capability "${capability}": campo "${field}" j\xE1 declarado (${shapeOf(previous)}) e redeclarado com valor diferente (${shapeOf(next)}) \u2014 declare uma vez s\xF3.`
+    );
+  }
+};
+function shapeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `array(${value.length})`;
+  if (typeof value === "object") {
+    return `object{${Object.keys(value).sort((a, b) => a.localeCompare(b)).join(",")}}`;
+  }
+  return typeof value;
+}
+__name(shapeOf, "shapeOf");
+function createDraft() {
+  return {
+    tools: [],
+    agents: {},
+    provenance: []
+  };
+}
+__name(createDraft, "createDraft");
+function applyCapabilities(capabilities, draft = createDraft()) {
+  for (const c of capabilities) c.apply(draft);
+  draft.stream ??= true;
+  return draft;
+}
+__name(applyCapabilities, "applyCapabilities");
+function setOnce(draft, field, value, capability) {
+  if (value === void 0) return;
+  const previous = draft[field];
+  if (previous !== void 0 && !isDeepStrictEqual(previous, value)) {
+    throw new CapabilityConflictError(field, previous, value, capability);
+  }
+  draft[field] = value;
+  draft.provenance.push({
+    capability,
+    contributed: [
+      field
+    ]
+  });
+}
+__name(setOnce, "setOnce");
+
+// src/capability/capabilities.ts
+var ConfigurationError = class extends Error {
+  static {
+    __name(this, "ConfigurationError");
+  }
+  name = "ConfigurationError";
+};
+function describe(value) {
+  if (value === null) return "null";
+  return Array.isArray(value) ? "array" : typeof value;
+}
+__name(describe, "describe");
+var ModelCapability = class {
+  static {
+    __name(this, "ModelCapability");
+  }
+  id;
+  reasoningEffort;
+  name = "model";
+  constructor(id, reasoningEffort) {
+    this.id = id;
+    this.reasoningEffort = reasoningEffort;
+    if (typeof id !== "string") {
+      throw new ConfigurationError(`model: esperava string, recebi ${describe(id)}`);
+    }
+    if (id.trim().length === 0) throw new ConfigurationError("model: id n\xE3o pode ser vazio");
+  }
+  apply(draft) {
+    setOnce(draft, "model", this.id, this.name);
+    if (this.reasoningEffort !== void 0) {
+      setOnce(draft, "reasoningEffort", this.reasoningEffort, this.name);
+    }
+  }
+};
+var ToolsCapability = class {
+  static {
+    __name(this, "ToolsCapability");
+  }
+  name = "tools";
+  #tools;
+  constructor(tools) {
+    this.#tools = tools;
+  }
+  apply(draft) {
+    draft.tools.push(...this.#tools);
+    draft.provenance.push({
+      capability: this.name,
+      contributed: [
+        "tools"
+      ]
+    });
+  }
+};
+var skills = /* @__PURE__ */ __name((entries) => {
+  if (!Array.isArray(entries)) {
+    throw new ConfigurationError(`skills: esperava array de nomes, recebi ${describe(entries)}`);
+  }
+  for (const e of entries) {
+    if (typeof e === "string") {
+      if (e.trim().length === 0) {
+        throw new ConfigurationError("skills: nome vazio \u2014 use um nome de skill n\xE3o vazio");
+      }
+      continue;
+    }
+    if (typeof e !== "object" || e === null || Array.isArray(e)) {
+      throw new ConfigurationError(`skills: entrada inv\xE1lida (${describe(e)}) \u2014 use um nome ou um skill inline`);
+    }
+    for (const field of [
+      "name",
+      "description",
+      "instructions"
+    ]) {
+      const value = e[field];
+      if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ConfigurationError(`skills: skill inline sem \`${field}\` v\xE1lido (${describe(value)}) \u2014 name, description e instructions s\xE3o obrigat\xF3rios`);
+      }
+    }
+  }
+  return {
+    name: "skills",
+    apply: /* @__PURE__ */ __name((draft) => {
+      const compiled = compileSkillsSelection(entries.slice());
+      if (compiled.skills === void 0) return;
+      const previous = draft.skills;
+      draft.skills = previous === void 0 ? compiled.skills : {
+        // The spread is exhaustive only because `compileSkillsSelection` emits a FIXED 3-key
+        // shape (`enabled`, `autoInject: true`, and `inline` iff non-empty) — `enabled` and
+        // `inline` are both re-derived below, and `autoInject` is the same literal on both
+        // sides. TRAP for the future: if a capability ever authors `autoInject: false`, this
+        // spread would silently normalize it back to `true`. Unreachable today (no capability
+        // and no reference array form can express it) — revisit when one can.
+        ...previous,
+        ...compiled.skills,
+        enabled: [
+          ...previous.enabled ?? [],
+          ...compiled.skills.enabled ?? []
+        ],
+        ...previous.inline !== void 0 || compiled.skills.inline !== void 0 ? {
+          inline: [
+            ...previous.inline ?? [],
+            ...compiled.skills.inline ?? []
+          ]
+        } : {}
+      };
+      draft.provenance.push({
+        capability: "skills",
+        contributed: [
+          "skills"
+        ]
+      });
+    }, "apply")
+  };
+}, "skills");
+
+// src/capability/registry.ts
+var UnknownCapabilityError = class extends Error {
+  static {
+    __name(this, "UnknownCapabilityError");
+  }
+  name = "UnknownCapabilityError";
+  constructor(requested, known) {
+    super(`capability "${requested}" n\xE3o registrada. Conhecidas: ${known.join(", ") || "(nenhuma)"}.`);
+  }
+};
+var CapabilityRegistry = class {
+  static {
+    __name(this, "CapabilityRegistry");
+  }
+  #factories = /* @__PURE__ */ new Map();
+  register(name, factory) {
+    this.#factories.set(name, factory);
+    return this;
+  }
+  has(name) {
+    return this.#factories.has(name);
+  }
+  names() {
+    return [
+      ...this.#factories.keys()
+    ];
+  }
+  resolve(name, arg) {
+    const factory = this.#factories.get(name);
+    if (factory === void 0) throw new UnknownCapabilityError(name, this.names());
+    return factory(arg);
+  }
+};
+var CapabilityPreset = class {
+  static {
+    __name(this, "CapabilityPreset");
+  }
+  name;
+  #members;
+  constructor(name, members) {
+    this.name = name;
+    this.#members = members;
+  }
+  apply(draft) {
+    for (const member of this.#members) member.apply(draft);
+  }
+};
+
+// src/capability/agent-capabilities.ts
+function fieldCapability(name, field) {
+  return (value) => ({
+    name,
+    apply: /* @__PURE__ */ __name((draft) => {
+      setOnce(draft, field, value, name);
+    }, "apply")
+  });
+}
+__name(fieldCapability, "fieldCapability");
+var memory = fieldCapability("memory", "memory");
+var contextWindow = /* @__PURE__ */ __name((options) => ({
+  name: "context-window",
+  apply: /* @__PURE__ */ __name((draft) => {
+    setOnce(draft, "context", compileContextWindow(options).context, "context-window");
+  }, "apply")
+}), "contextWindow");
+var projectContext = fieldCapability("project-context", "projectContext");
+var mcpServers = fieldCapability("mcp", "mcpServers");
+var guardrails = fieldCapability("guardrails", "guardrails");
+var checkpoint = /* @__PURE__ */ __name((options) => ({
+  name: "checkpoint",
+  apply: /* @__PURE__ */ __name((draft) => {
+    if (options !== void 0 && options.storage !== "filesystem") {
+      console.warn(`[THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY] checkpoint({ storage: '${options.storage ?? "memory"}' }) does NOT resume across requests \u2014 only 'filesystem' selects the SDK's durable conversation store. Use checkpoint({ storage: 'filesystem' }) for cross-request resume.`);
+    }
+    setOnce(draft, "checkpoint", options, "checkpoint");
+  }, "apply")
+}), "checkpoint");
+var humanInTheLoop = fieldCapability("human-in-the-loop", "hitl");
+var subAgents = /* @__PURE__ */ __name((children) => ({
+  name: "sub-agents",
+  apply: /* @__PURE__ */ __name((draft) => {
+    for (const [name, child] of Object.entries(children)) {
+      if (name in draft.agents && draft.agents[name] !== child) {
+        throw new ConfigurationError(`sub-agents: filho "${name}" declarado duas vezes com defini\xE7\xF5es diferentes`);
+      }
+      draft.agents[name] = child;
+    }
+    draft.provenance.push({
+      capability: "sub-agents",
+      contributed: [
+        "agents"
+      ]
+    });
+  }, "apply")
+}), "subAgents");
+var skillsOptions = /* @__PURE__ */ __name((options) => ({
+  name: "skills",
+  apply: /* @__PURE__ */ __name((draft) => {
+    setOnce(draft, "skills", compileSkills(options), "skills");
+  }, "apply")
+}), "skillsOptions");
+var settingSources = fieldCapability("setting-sources", "settingSources");
+var plugins = fieldCapability("plugins", "plugins");
+var runContext = fieldCapability("run-context", "runContext");
+var skillsResolver = fieldCapability("skills-resolver", "skillsResolver");
+var AgentConfigCapability = class {
+  static {
+    __name(this, "AgentConfigCapability");
+  }
+  config;
+  name = "agent-config";
+  constructor(config) {
+    this.config = config;
+    if (typeof config !== "object" || config === null) {
+      throw new ConfigurationError("agent-config: esperava um objeto de configura\xE7\xE3o");
+    }
+    for (const field of [
+      "maxIterations",
+      "timeoutMs"
+    ]) {
+      const value = config[field];
+      if (value !== void 0 && (!Number.isFinite(value) || value <= 0)) {
+        throw new ConfigurationError(`agent-config: \`${field}\` deve ser um n\xFAmero positivo`);
+      }
+    }
+  }
+  apply(draft) {
+    const claimedByMainLoop = /* @__PURE__ */ __name((field) => draft.provenance.some((p) => p.capability === "main-loop" && p.contributed.includes(field)), "claimedByMainLoop");
+    if (!claimedByMainLoop("maxIterations")) {
+      setOnce(draft, "maxIterations", this.config.maxIterations, this.name);
+    }
+    if (!claimedByMainLoop("timeoutMs")) {
+      setOnce(draft, "timeoutMs", this.config.timeoutMs, this.name);
+    }
+    setOnce(draft, "systemPrompt", this.config.systemPrompt, this.name);
+    setOnce(draft, "parseThinkTags", this.config.parseThinkTags, this.name);
+    setOnce(draft, "stripToolDialect", this.config.stripToolDialect, this.name);
+    setOnce(draft, "recoverLeakedToolCalls", this.config.recoverLeakedToolCalls, this.name);
+    setOnce(draft, "stream", this.config.stream, this.name);
+  }
+};
+var MainLoopCapability = class {
+  static {
+    __name(this, "MainLoopCapability");
+  }
+  config;
+  name = "main-loop";
+  constructor(config) {
+    this.config = config;
+  }
+  apply(draft) {
+    const contributed = [];
+    if (this.config.maxIterations !== void 0) {
+      draft.maxIterations = this.config.maxIterations;
+      contributed.push("maxIterations");
+    }
+    if (this.config.timeoutMs !== void 0) {
+      draft.timeoutMs = this.config.timeoutMs;
+      contributed.push("timeoutMs");
+    }
+    if (contributed.length > 0) draft.provenance.push({
+      capability: this.name,
+      contributed
+    });
+  }
+};
+
+// src/capability/toolbox.ts
+var ToolboxCapability = class {
+  static {
+    __name(this, "ToolboxCapability");
+  }
+  name = "toolbox";
+  #instance;
+  #declarations;
+  #namespace;
+  constructor(instance, options = {}) {
+    if (typeof instance !== "object" || instance === null) {
+      throw new ConfigurationError("toolbox: esperava uma inst\xE2ncia de toolbox");
+    }
+    const declared = options.tools ?? instance.constructor.tools;
+    if (declared === void 0 || declared.length === 0) {
+      throw new ConfigurationError(`toolbox: ${instance.constructor.name} n\xE3o declara tools \u2014 use \`static tools = [...]\` ou a op\xE7\xE3o \`tools\``);
+    }
+    for (const tool of declared) {
+      if (typeof instance[tool.method] !== "function") {
+        throw new ConfigurationError(`toolbox: ${instance.constructor.name}.${tool.method} n\xE3o \xE9 um m\xE9todo (tool "${tool.name}")`);
+      }
+    }
+    this.#instance = instance;
+    this.#declarations = declared;
+    this.#namespace = options.namespace ?? "";
+  }
+  /** The compiled tools this toolbox contributes — the same shape the decorator path produces. */
+  compile() {
+    const token = this.#instance.constructor;
+    const walk = {
+      class: token,
+      namespace: this.#namespace,
+      guards: [],
+      tools: this.#declarations.map((tool) => ({
+        propertyKey: tool.method,
+        config: tool,
+        guards: [],
+        approval: tool.approval,
+        trace: tool.trace ?? false,
+        audit: tool.audit ?? false,
+        ...tool.hitl !== void 0 ? {
+          hitl: tool.hitl
+        } : {}
+      }))
+    };
+    return compileTools([
+      walk
+    ], /* @__PURE__ */ new Map([
+      [
+        token,
+        this.#instance
+      ]
+    ]));
+  }
+  apply(draft) {
+    draft.tools.push(...this.compile());
+    draft.provenance.push({
+      capability: this.name,
+      contributed: [
+        "tools"
+      ]
+    });
+    const gates = [];
+    for (const tool of this.#declarations) {
+      if (tool.hitl === void 0) continue;
+      gates.push([
+        this.#namespace === "" ? tool.name : `${this.#namespace}.${tool.name}`,
+        tool.hitl
+      ]);
+    }
+    if (gates.length === 0) return;
+    draft.hitl ??= /* @__PURE__ */ new Map();
+    for (const [key, options] of gates) draft.hitl.set(key, options);
+    draft.provenance.push({
+      capability: this.name,
+      contributed: [
+        "hitl"
+      ]
+    });
+  }
+};
+
 // src/a2a/agent-card.ts
 function trimTrailingSlash(url) {
   return url.endsWith("/") ? url.slice(0, -1) : url;
@@ -212,8 +626,12 @@ async function resolveEnabledSkills(selection, ctx) {
   if (!Array.isArray(resolved)) {
     throw new Error("[@theokit/agents] skills resolver must return an array of skill names");
   }
+  const names = resolved;
+  if (!names.every((n) => typeof n === "string" && n.trim().length > 0)) {
+    throw new Error("[@theokit/agents] skills resolver must return non-empty skill NAME strings");
+  }
   return [
-    ...resolved
+    ...names
   ];
 }
 __name(resolveEnabledSkills, "resolveEnabledSkills");
@@ -347,35 +765,47 @@ export {
   AGENT_BRAND,
   AcpClient,
   AcpMessageDecoder,
+  AgentConfigCapability,
   AgentDefinitionError,
   AgentRunner,
   AgentRunnerBuilder,
-  AgentWarningCode,
   BudgetExceededError,
+  CapabilityConflictError,
+  CapabilityPreset,
+  CapabilityRegistry,
+  ConfigurationError,
   CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
   DEFAULT_MAX_ITERATIONS,
   DelegationError,
   GuardrailViolationError,
   MCP_PROTOCOL_VERSION,
+  MainLoopCapability,
+  ModelCapability,
+  ToolboxCapability,
+  ToolsCapability,
+  UnknownCapabilityError,
   agent,
   agentsPlugin,
+  applyCapabilities,
   buildAgentCard,
   buildMcpToolDescriptors,
   buildModelSelection,
+  checkpoint,
   compactionStrategyConfigSchema,
-  compileAgent,
   compileAgentDefinition,
   compileAgentModule,
   compileContextWindow,
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextWindow,
   contextualTool,
   costGuard,
   createA2ATool,
   createAgentExecutionContext,
   createApiErrorHandler,
+  createDraft,
   createSdkAgentStream,
   createThinkTagExtractor,
   createToolHooksPlugin,
@@ -388,6 +818,8 @@ export {
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
+  guardrails,
+  humanInTheLoop,
   isAgentContext,
   isAgentDefinition,
   isApprovalRequired,
@@ -401,13 +833,17 @@ export {
   loopStrategyConfigSchema,
   mcpRegistry,
   mcpServerInfo,
+  mcpServers,
   mcpToolApprovals,
+  memory,
   moderateOutputStream,
   noopReflectionStrategy,
   outputModeration,
   parseConversationId,
   piiDetector,
+  plugins,
   presentUIMessageStream,
+  projectContext,
   projectContextMetadataOnlyKnobs,
   promptInjectionDetector,
   reflectionStrategyConfigSchema,
@@ -415,17 +851,22 @@ export {
   resolveEnabledSkills,
   resolveLoopStrategy,
   resolveMcpServers,
+  runContext,
   runInputGuards,
   runOutputGuards,
   runWithApiErrorHandling,
+  setOnce,
+  settingSources,
+  skills,
+  skillsOptions,
+  skillsResolver,
   streamAgentResponse,
   streamAgentUIMessages,
+  subAgents,
   toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   unicodeNormalizer,
-  validateUniqueRoutes,
-  walkAgentMetadata,
   wellKnownCardPath
 };
 //# sourceMappingURL=index.js.map