@nhtio/adk 1.20260607.0 → 1.20260607.2

package/CHANGELOG.md

@@ -9,6 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **SoDK — a mental-model doc that teaches the loop in human terms.** A new page,
+  `docs/sodk.md` ("Society Development Kit"), retells [How agents work](https://adk.nht.io/how-agents-work)
+  and [What ADK is](https://adk.nht.io/what-adk-is) with exactly one noun swapped: where ADK says
+  *model*, SoDK says *person*. It is a teaching device for the reader who can't yet see why an agent
+  is the loop, not the LLM — role↔agent, task↔turn, briefing↔context, request↔tool, process↔middleware,
+  "say where things get filed"↔the required storage callbacks. The human-facing prose plays it
+  straight; the `<llm-only>` block names the metaphor outright and carries the full 1:1 map, so an
+  agent answering a question can explain a concept *through* the framing or translate either way. Wired
+  into the sidebar and home listing, and cross-linked from both source docs. Docs only — no code, types,
+  or package surface change.
+
+- **Importable ESLint plugin (`@nhtio/adk/eslint`).** The harness's documented contracts are now
+  machine-checkable: a flat-config plugin that flags footguns the TypeScript compiler cannot see
+  because they live in runtime validators or conventions, not types. Five rules ship —
+  `require-validator-any-required` (a `validator.any()` chain with no explicit
+  `.required()`/`.optional()`/`.default()`/`.forbidden()` silently admits null/undefined),
+  `thought-payload-requires-replay-tag` (a `Thought` with a vendor `payload` but no
+  `replayCompatibility` can never be safely replayed), `token-encoding-requires-context-window` (a
+  Chat Completions adapter that counts tokens with no budget never runs its overflow guard),
+  `artifact-tool-forbids-artifact-constructor` (an `ArtifactTool` that wraps another artifact
+  recurses forever), and `no-model-in-tool-handler` (a model call inside a tool handler hides an
+  unmanaged dispatch — unless the handler runs its own scoped sub-agent via `new TurnRunner(...)` or
+  `DispatchRunner.dispatch(...)`). Import the assembled plugin
+  from `@nhtio/adk/eslint` (or `adk.configs.recommended` for all five), or individual rules from
+  `@nhtio/adk/eslint/rules/<name>`. `eslint` and `@typescript-eslint/utils` are **optional peers** —
+  installed only by consumers who lint with the plugin. Rules are report-only with inline
+  `eslint-disable` carve-outs. See the new **Developer Tools** docs section, which also now houses
+  the ADK Assembly MCP guide.
+
 - **Vector conformance harness is now public (`@nhtio/adk/batteries/vector/conformance`).** The
   `runVectorStoreConformance` suite (plus `stubEncoder` / `paddedStubEncoder`) that the 29 shipped
   adapters test against is now an exported, deep-import-only subpath, so anyone writing their own

package/common-BUIjZ6LV.mjs

@@ -0,0 +1,119 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+//#region src/eslint/rules/common.ts
+/**
+* Shared `createRule` factory for the published `@nhtio/adk` ESLint rules.
+*
+* @remarks
+* Wraps `ESLintUtils.RuleCreator` so every rule gets a consistent `meta.docs.url` pointing at the
+* published rule reference. Each rule module imports this and default-exports `createRule({...})`.
+*
+* `@typescript-eslint/utils` is an OPTIONAL peer dependency of `@nhtio/adk` — it is only needed by
+* consumers who import `@nhtio/adk/eslint`. The main library never imports this module.
+*/
+/**
+* Rule factory for `@nhtio/adk` ESLint rules. The `name` passed to each rule becomes the slug in the
+* generated documentation URL.
+*/
+var createRule = ESLintUtils.RuleCreator((name) => `https://adk.nht.io/eslint/rules/${name}`);
+var isFunctionNode = (node) => node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+var LLM_CTOR_NAMES = new Set([
+	"OpenAI",
+	"AzureOpenAI",
+	"Anthropic",
+	"AnthropicBedrock",
+	"AnthropicVertex",
+	"GoogleGenerativeAI",
+	"GoogleGenAI",
+	"Mistral",
+	"CohereClient",
+	"CohereClientV2",
+	"Groq"
+]);
+var LLM_METHOD_NAMES = new Set([
+	"generateContent",
+	"generateContentStream",
+	"generateMessage"
+]);
+var memberPropertyName = (node) => node.property.type === "Identifier" ? node.property.name : void 0;
+/**
+* Heuristic: does this call/new expression look like a primary LLM invocation? Detects known
+* provider SDK constructors and `…create()` calls whose receiver chain passes through
+* `chat`/`completions`/`messages`/`responses`, plus a small set of generate* methods. Deliberately
+* conservative — the goal is to catch the obvious footgun, not to be exhaustive.
+*/
+var isLlmCall = (node) => {
+	if (node.type === "NewExpression") return node.callee.type === "Identifier" && LLM_CTOR_NAMES.has(node.callee.name);
+	if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
+		const method = memberPropertyName(node.callee);
+		if (method && LLM_METHOD_NAMES.has(method)) return true;
+		if (method === "create") {
+			let cur = node.callee.object;
+			while (cur.type === "MemberExpression") {
+				const seg = memberPropertyName(cur);
+				if (seg === "completions" || seg === "messages" || seg === "responses") return true;
+				cur = cur.object;
+			}
+		}
+	}
+	return false;
+};
+/**
+* Walks the descendants of a function body (NOT crossing into nested function scopes) and invokes
+* `visit` for every node, so a rule can scan a handler/middleware body for a pattern while ignoring
+* inner closures (e.g. a `new TurnRunner` sub-agent's own callbacks).
+*/
+var walkBodySkippingNestedFunctions = (body, visit) => {
+	const recurse = (node) => {
+		visit(node);
+		for (const key of Object.keys(node)) {
+			if (key === "parent") continue;
+			const value = node[key];
+			const children = Array.isArray(value) ? value : [value];
+			for (const child of children) {
+				if (!child || typeof child !== "object") continue;
+				const childNode = child;
+				if (typeof childNode.type !== "string") continue;
+				if (isFunctionNode(childNode)) continue;
+				recurse(childNode);
+			}
+		}
+	};
+	recurse(body);
+};
+var isSubAgentEntry = (node) => {
+	if (node.type === "NewExpression" && node.callee.type === "Identifier" && node.callee.name === "TurnRunner") return true;
+	if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && node.callee.property.type === "Identifier" && node.callee.property.name === "dispatch" && node.callee.object.type === "Identifier" && node.callee.object.name === "DispatchRunner") return true;
+	return false;
+};
+/**
+* True when the function body runs a scoped sub-agent — either `new TurnRunner(...)` or
+* `DispatchRunner.dispatch(...)` — the documented escape hatch that exempts a tool handler from
+* {@link isLlmCall} flagging.
+*/
+var runsSubAgent = (body) => {
+	let found = false;
+	const recurse = (node) => {
+		if (found) return;
+		if (isSubAgentEntry(node)) {
+			found = true;
+			return;
+		}
+		for (const key of Object.keys(node)) {
+			if (key === "parent") continue;
+			const value = node[key];
+			const children = Array.isArray(value) ? value : [value];
+			for (const child of children) {
+				if (!child || typeof child !== "object") continue;
+				const childNode = child;
+				if (typeof childNode.type !== "string") continue;
+				recurse(childNode);
+			}
+		}
+	};
+	recurse(body);
+	return found;
+};
+//#endregion
+export { walkBodySkippingNestedFunctions as a, runsSubAgent as i, isFunctionNode as n, isLlmCall as r, createRule as t };
+
+//# sourceMappingURL=common-BUIjZ6LV.mjs.map

package/common-BUIjZ6LV.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"common-BUIjZ6LV.mjs","names":[],"sources":["../src/eslint/rules/common.ts"],"sourcesContent":["/**\n * Shared `createRule` factory for the published `@nhtio/adk` ESLint rules.\n *\n * @remarks\n * Wraps `ESLintUtils.RuleCreator` so every rule gets a consistent `meta.docs.url` pointing at the\n * published rule reference. Each rule module imports this and default-exports `createRule({...})`.\n *\n * `@typescript-eslint/utils` is an OPTIONAL peer dependency of `@nhtio/adk` — it is only needed by\n * consumers who import `@nhtio/adk/eslint`. The main library never imports this module.\n */\n\nimport { ESLintUtils } from '@typescript-eslint/utils'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\n/**\n * Rule factory for `@nhtio/adk` ESLint rules. The `name` passed to each rule becomes the slug in the\n * generated documentation URL.\n */\nexport const createRule = ESLintUtils.RuleCreator(\n  (name) => `https://adk.nht.io/eslint/rules/${name}`\n)\n\n/** Any function-like AST node (arrow, function expression, or declaration). */\nexport type FunctionNode =\n  | TSESTree.FunctionDeclaration\n  | TSESTree.FunctionExpression\n  | TSESTree.ArrowFunctionExpression\n\nexport const isFunctionNode = (node: TSESTree.Node): node is FunctionNode =>\n  node.type === 'FunctionDeclaration' ||\n  node.type === 'FunctionExpression' ||\n  node.type === 'ArrowFunctionExpression'\n\n// Provider SDK constructor names whose presence inside a handler/middleware indicates a primary\n// model call. Conservative, well-known set — keeps false positives low.\nconst LLM_CTOR_NAMES = new Set([\n  'OpenAI',\n  'AzureOpenAI',\n  'Anthropic',\n  'AnthropicBedrock',\n  'AnthropicVertex',\n  'GoogleGenerativeAI',\n  'GoogleGenAI',\n  'Mistral',\n  'CohereClient',\n  'CohereClientV2',\n  'Groq',\n])\n\n// Method-name tails that indicate a chat/completion/generation call on a provider client, e.g.\n// `client.chat.completions.create(...)`, `client.messages.create(...)`, `model.generateContent(...)`.\nconst LLM_METHOD_NAMES = new Set(['generateContent', 'generateContentStream', 'generateMessage'])\n\nconst memberPropertyName = (node: TSESTree.MemberExpression): string | undefined =>\n  node.property.type === 'Identifier' ? node.property.name : undefined\n\n/**\n * Heuristic: does this call/new expression look like a primary LLM invocation? Detects known\n * provider SDK constructors and `…create()` calls whose receiver chain passes through\n * `chat`/`completions`/`messages`/`responses`, plus a small set of generate* methods. Deliberately\n * conservative — the goal is to catch the obvious footgun, not to be exhaustive.\n */\nexport const isLlmCall = (node: TSESTree.Node): boolean => {\n  if (node.type === 'NewExpression') {\n    return node.callee.type === 'Identifier' && LLM_CTOR_NAMES.has(node.callee.name)\n  }\n  if (node.type === 'CallExpression' && node.callee.type === 'MemberExpression') {\n    const method = memberPropertyName(node.callee)\n    if (method && LLM_METHOD_NAMES.has(method)) return true\n    // `<chain>.create()` where the chain passes through a provider sub-resource.\n    if (method === 'create') {\n      let cur: TSESTree.Node = node.callee.object\n      while (cur.type === 'MemberExpression') {\n        const seg = memberPropertyName(cur)\n        if (seg === 'completions' || seg === 'messages' || seg === 'responses') return true\n        cur = cur.object\n      }\n    }\n  }\n  return false\n}\n\n/**\n * Walks the descendants of a function body (NOT crossing into nested function scopes) and invokes\n * `visit` for every node, so a rule can scan a handler/middleware body for a pattern while ignoring\n * inner closures (e.g. a `new TurnRunner` sub-agent's own callbacks).\n */\nexport const walkBodySkippingNestedFunctions = (\n  body: TSESTree.Node,\n  visit: (node: TSESTree.Node) => void\n): void => {\n  const recurse = (node: TSESTree.Node): void => {\n    visit(node)\n    for (const key of Object.keys(node)) {\n      if (key === 'parent') continue\n      const value = (node as unknown as Record<string, unknown>)[key]\n      const children = Array.isArray(value) ? value : [value]\n      for (const child of children) {\n        if (!child || typeof child !== 'object') continue\n        const childNode = child as TSESTree.Node\n        if (typeof childNode.type !== 'string') continue\n        // Do not descend into nested function scopes — their calls belong to a different context.\n        if (isFunctionNode(childNode)) continue\n        recurse(childNode)\n      }\n    }\n  }\n  recurse(body)\n}\n\n// A sub-agent is run through one of two blessed entry points: constructing a scoped\n// `new TurnRunner(...)`, or the lower-level static `DispatchRunner.dispatch(...)` (its constructor\n// is token-gated private, so `dispatch()` is the real entry point). Either one inside a tool handler\n// means \"this tool is deliberately a sub-agent,\" which is the documented exception to\n// no-model-in-tool-handler.\nconst isSubAgentEntry = (node: TSESTree.Node): boolean => {\n  // new TurnRunner(...)\n  if (\n    node.type === 'NewExpression' &&\n    node.callee.type === 'Identifier' &&\n    node.callee.name === 'TurnRunner'\n  ) {\n    return true\n  }\n  // DispatchRunner.dispatch(...)\n  if (\n    node.type === 'CallExpression' &&\n    node.callee.type === 'MemberExpression' &&\n    node.callee.property.type === 'Identifier' &&\n    node.callee.property.name === 'dispatch' &&\n    node.callee.object.type === 'Identifier' &&\n    node.callee.object.name === 'DispatchRunner'\n  ) {\n    return true\n  }\n  return false\n}\n\n/**\n * True when the function body runs a scoped sub-agent — either `new TurnRunner(...)` or\n * `DispatchRunner.dispatch(...)` — the documented escape hatch that exempts a tool handler from\n * {@link isLlmCall} flagging.\n */\nexport const runsSubAgent = (body: TSESTree.Node): boolean => {\n  let found = false\n  const recurse = (node: TSESTree.Node): void => {\n    if (found) return\n    if (isSubAgentEntry(node)) {\n      found = true\n      return\n    }\n    for (const key of Object.keys(node)) {\n      if (key === 'parent') continue\n      const value = (node as unknown as Record<string, unknown>)[key]\n      const children = Array.isArray(value) ? value : [value]\n      for (const child of children) {\n        if (!child || typeof child !== 'object') continue\n        const childNode = child as TSESTree.Node\n        if (typeof childNode.type !== 'string') continue\n        recurse(childNode)\n      }\n    }\n  }\n  recurse(body)\n  return found\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAmBA,IAAa,aAAa,YAAY,aACnC,SAAS,mCAAmC,MAC/C;AAQA,IAAa,kBAAkB,SAC7B,KAAK,SAAS,yBACd,KAAK,SAAS,wBACd,KAAK,SAAS;AAIhB,IAAM,iBAAiB,IAAI,IAAI;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAID,IAAM,mBAAmB,IAAI,IAAI;CAAC;CAAmB;CAAyB;AAAiB,CAAC;AAEhG,IAAM,sBAAsB,SAC1B,KAAK,SAAS,SAAS,eAAe,KAAK,SAAS,OAAO,KAAA;;;;;;;AAQ7D,IAAa,aAAa,SAAiC;CACzD,IAAI,KAAK,SAAS,iBAChB,OAAO,KAAK,OAAO,SAAS,gBAAgB,eAAe,IAAI,KAAK,OAAO,IAAI;CAEjF,IAAI,KAAK,SAAS,oBAAoB,KAAK,OAAO,SAAS,oBAAoB;EAC7E,MAAM,SAAS,mBAAmB,KAAK,MAAM;EAC7C,IAAI,UAAU,iBAAiB,IAAI,MAAM,GAAG,OAAO;EAEnD,IAAI,WAAW,UAAU;GACvB,IAAI,MAAqB,KAAK,OAAO;GACrC,OAAO,IAAI,SAAS,oBAAoB;IACtC,MAAM,MAAM,mBAAmB,GAAG;IAClC,IAAI,QAAQ,iBAAiB,QAAQ,cAAc,QAAQ,aAAa,OAAO;IAC/E,MAAM,IAAI;GACZ;EACF;CACF;CACA,OAAO;AACT;;;;;;AAOA,IAAa,mCACX,MACA,UACS;CACT,MAAM,WAAW,SAA8B;EAC7C,MAAM,IAAI;EACV,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,GAAG;GACnC,IAAI,QAAQ,UAAU;GACtB,MAAM,QAAS,KAA4C;GAC3D,MAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;GACtD,KAAK,MAAM,SAAS,UAAU;IAC5B,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU;IACzC,MAAM,YAAY;IAClB,IAAI,OAAO,UAAU,SAAS,UAAU;IAExC,IAAI,eAAe,SAAS,GAAG;IAC/B,QAAQ,SAAS;GACnB;EACF;CACF;CACA,QAAQ,IAAI;AACd;AAOA,IAAM,mBAAmB,SAAiC;CAExD,IACE,KAAK,SAAS,mBACd,KAAK,OAAO,SAAS,gBACrB,KAAK,OAAO,SAAS,cAErB,OAAO;CAGT,IACE,KAAK,SAAS,oBACd,KAAK,OAAO,SAAS,sBACrB,KAAK,OAAO,SAAS,SAAS,gBAC9B,KAAK,OAAO,SAAS,SAAS,cAC9B,KAAK,OAAO,OAAO,SAAS,gBAC5B,KAAK,OAAO,OAAO,SAAS,kBAE5B,OAAO;CAET,OAAO;AACT;;;;;;AAOA,IAAa,gBAAgB,SAAiC;CAC5D,IAAI,QAAQ;CACZ,MAAM,WAAW,SAA8B;EAC7C,IAAI,OAAO;EACX,IAAI,gBAAgB,IAAI,GAAG;GACzB,QAAQ;GACR;EACF;EACA,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,GAAG;GACnC,IAAI,QAAQ,UAAU;GACtB,MAAM,QAAS,KAA4C;GAC3D,MAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;GACtD,KAAK,MAAM,SAAS,UAAU;IAC5B,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU;IACzC,MAAM,YAAY;IAClB,IAAI,OAAO,UAAU,SAAS,UAAU;IACxC,QAAQ,SAAS;GACnB;EACF;CACF;CACA,QAAQ,IAAI;CACZ,OAAO;AACT"}

package/common-DeNipTQI.js

@@ -0,0 +1,148 @@
+require("./chunk-Ble4zEEl.js");
+//#region src/eslint/rules/common.ts
+/**
+* Shared `createRule` factory for the published `@nhtio/adk` ESLint rules.
+*
+* @remarks
+* Wraps `ESLintUtils.RuleCreator` so every rule gets a consistent `meta.docs.url` pointing at the
+* published rule reference. Each rule module imports this and default-exports `createRule({...})`.
+*
+* `@typescript-eslint/utils` is an OPTIONAL peer dependency of `@nhtio/adk` — it is only needed by
+* consumers who import `@nhtio/adk/eslint`. The main library never imports this module.
+*/
+/**
+* Rule factory for `@nhtio/adk` ESLint rules. The `name` passed to each rule becomes the slug in the
+* generated documentation URL.
+*/
+var createRule = require("@typescript-eslint/utils").ESLintUtils.RuleCreator((name) => `https://adk.nht.io/eslint/rules/${name}`);
+var isFunctionNode = (node) => node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression";
+var LLM_CTOR_NAMES = new Set([
+	"OpenAI",
+	"AzureOpenAI",
+	"Anthropic",
+	"AnthropicBedrock",
+	"AnthropicVertex",
+	"GoogleGenerativeAI",
+	"GoogleGenAI",
+	"Mistral",
+	"CohereClient",
+	"CohereClientV2",
+	"Groq"
+]);
+var LLM_METHOD_NAMES = new Set([
+	"generateContent",
+	"generateContentStream",
+	"generateMessage"
+]);
+var memberPropertyName = (node) => node.property.type === "Identifier" ? node.property.name : void 0;
+/**
+* Heuristic: does this call/new expression look like a primary LLM invocation? Detects known
+* provider SDK constructors and `…create()` calls whose receiver chain passes through
+* `chat`/`completions`/`messages`/`responses`, plus a small set of generate* methods. Deliberately
+* conservative — the goal is to catch the obvious footgun, not to be exhaustive.
+*/
+var isLlmCall = (node) => {
+	if (node.type === "NewExpression") return node.callee.type === "Identifier" && LLM_CTOR_NAMES.has(node.callee.name);
+	if (node.type === "CallExpression" && node.callee.type === "MemberExpression") {
+		const method = memberPropertyName(node.callee);
+		if (method && LLM_METHOD_NAMES.has(method)) return true;
+		if (method === "create") {
+			let cur = node.callee.object;
+			while (cur.type === "MemberExpression") {
+				const seg = memberPropertyName(cur);
+				if (seg === "completions" || seg === "messages" || seg === "responses") return true;
+				cur = cur.object;
+			}
+		}
+	}
+	return false;
+};
+/**
+* Walks the descendants of a function body (NOT crossing into nested function scopes) and invokes
+* `visit` for every node, so a rule can scan a handler/middleware body for a pattern while ignoring
+* inner closures (e.g. a `new TurnRunner` sub-agent's own callbacks).
+*/
+var walkBodySkippingNestedFunctions = (body, visit) => {
+	const recurse = (node) => {
+		visit(node);
+		for (const key of Object.keys(node)) {
+			if (key === "parent") continue;
+			const value = node[key];
+			const children = Array.isArray(value) ? value : [value];
+			for (const child of children) {
+				if (!child || typeof child !== "object") continue;
+				const childNode = child;
+				if (typeof childNode.type !== "string") continue;
+				if (isFunctionNode(childNode)) continue;
+				recurse(childNode);
+			}
+		}
+	};
+	recurse(body);
+};
+var isSubAgentEntry = (node) => {
+	if (node.type === "NewExpression" && node.callee.type === "Identifier" && node.callee.name === "TurnRunner") return true;
+	if (node.type === "CallExpression" && node.callee.type === "MemberExpression" && node.callee.property.type === "Identifier" && node.callee.property.name === "dispatch" && node.callee.object.type === "Identifier" && node.callee.object.name === "DispatchRunner") return true;
+	return false;
+};
+/**
+* True when the function body runs a scoped sub-agent — either `new TurnRunner(...)` or
+* `DispatchRunner.dispatch(...)` — the documented escape hatch that exempts a tool handler from
+* {@link isLlmCall} flagging.
+*/
+var runsSubAgent = (body) => {
+	let found = false;
+	const recurse = (node) => {
+		if (found) return;
+		if (isSubAgentEntry(node)) {
+			found = true;
+			return;
+		}
+		for (const key of Object.keys(node)) {
+			if (key === "parent") continue;
+			const value = node[key];
+			const children = Array.isArray(value) ? value : [value];
+			for (const child of children) {
+				if (!child || typeof child !== "object") continue;
+				const childNode = child;
+				if (typeof childNode.type !== "string") continue;
+				recurse(childNode);
+			}
+		}
+	};
+	recurse(body);
+	return found;
+};
+//#endregion
+Object.defineProperty(exports, "createRule", {
+	enumerable: true,
+	get: function() {
+		return createRule;
+	}
+});
+Object.defineProperty(exports, "isFunctionNode", {
+	enumerable: true,
+	get: function() {
+		return isFunctionNode;
+	}
+});
+Object.defineProperty(exports, "isLlmCall", {
+	enumerable: true,
+	get: function() {
+		return isLlmCall;
+	}
+});
+Object.defineProperty(exports, "runsSubAgent", {
+	enumerable: true,
+	get: function() {
+		return runsSubAgent;
+	}
+});
+Object.defineProperty(exports, "walkBodySkippingNestedFunctions", {
+	enumerable: true,
+	get: function() {
+		return walkBodySkippingNestedFunctions;
+	}
+});
+
+//# sourceMappingURL=common-DeNipTQI.js.map

package/common-DeNipTQI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common-DeNipTQI.js","names":[],"sources":["../src/eslint/rules/common.ts"],"sourcesContent":["/**\n * Shared `createRule` factory for the published `@nhtio/adk` ESLint rules.\n *\n * @remarks\n * Wraps `ESLintUtils.RuleCreator` so every rule gets a consistent `meta.docs.url` pointing at the\n * published rule reference. Each rule module imports this and default-exports `createRule({...})`.\n *\n * `@typescript-eslint/utils` is an OPTIONAL peer dependency of `@nhtio/adk` — it is only needed by\n * consumers who import `@nhtio/adk/eslint`. The main library never imports this module.\n */\n\nimport { ESLintUtils } from '@typescript-eslint/utils'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\n/**\n * Rule factory for `@nhtio/adk` ESLint rules. The `name` passed to each rule becomes the slug in the\n * generated documentation URL.\n */\nexport const createRule = ESLintUtils.RuleCreator(\n  (name) => `https://adk.nht.io/eslint/rules/${name}`\n)\n\n/** Any function-like AST node (arrow, function expression, or declaration). */\nexport type FunctionNode =\n  | TSESTree.FunctionDeclaration\n  | TSESTree.FunctionExpression\n  | TSESTree.ArrowFunctionExpression\n\nexport const isFunctionNode = (node: TSESTree.Node): node is FunctionNode =>\n  node.type === 'FunctionDeclaration' ||\n  node.type === 'FunctionExpression' ||\n  node.type === 'ArrowFunctionExpression'\n\n// Provider SDK constructor names whose presence inside a handler/middleware indicates a primary\n// model call. Conservative, well-known set — keeps false positives low.\nconst LLM_CTOR_NAMES = new Set([\n  'OpenAI',\n  'AzureOpenAI',\n  'Anthropic',\n  'AnthropicBedrock',\n  'AnthropicVertex',\n  'GoogleGenerativeAI',\n  'GoogleGenAI',\n  'Mistral',\n  'CohereClient',\n  'CohereClientV2',\n  'Groq',\n])\n\n// Method-name tails that indicate a chat/completion/generation call on a provider client, e.g.\n// `client.chat.completions.create(...)`, `client.messages.create(...)`, `model.generateContent(...)`.\nconst LLM_METHOD_NAMES = new Set(['generateContent', 'generateContentStream', 'generateMessage'])\n\nconst memberPropertyName = (node: TSESTree.MemberExpression): string | undefined =>\n  node.property.type === 'Identifier' ? node.property.name : undefined\n\n/**\n * Heuristic: does this call/new expression look like a primary LLM invocation? Detects known\n * provider SDK constructors and `…create()` calls whose receiver chain passes through\n * `chat`/`completions`/`messages`/`responses`, plus a small set of generate* methods. Deliberately\n * conservative — the goal is to catch the obvious footgun, not to be exhaustive.\n */\nexport const isLlmCall = (node: TSESTree.Node): boolean => {\n  if (node.type === 'NewExpression') {\n    return node.callee.type === 'Identifier' && LLM_CTOR_NAMES.has(node.callee.name)\n  }\n  if (node.type === 'CallExpression' && node.callee.type === 'MemberExpression') {\n    const method = memberPropertyName(node.callee)\n    if (method && LLM_METHOD_NAMES.has(method)) return true\n    // `<chain>.create()` where the chain passes through a provider sub-resource.\n    if (method === 'create') {\n      let cur: TSESTree.Node = node.callee.object\n      while (cur.type === 'MemberExpression') {\n        const seg = memberPropertyName(cur)\n        if (seg === 'completions' || seg === 'messages' || seg === 'responses') return true\n        cur = cur.object\n      }\n    }\n  }\n  return false\n}\n\n/**\n * Walks the descendants of a function body (NOT crossing into nested function scopes) and invokes\n * `visit` for every node, so a rule can scan a handler/middleware body for a pattern while ignoring\n * inner closures (e.g. a `new TurnRunner` sub-agent's own callbacks).\n */\nexport const walkBodySkippingNestedFunctions = (\n  body: TSESTree.Node,\n  visit: (node: TSESTree.Node) => void\n): void => {\n  const recurse = (node: TSESTree.Node): void => {\n    visit(node)\n    for (const key of Object.keys(node)) {\n      if (key === 'parent') continue\n      const value = (node as unknown as Record<string, unknown>)[key]\n      const children = Array.isArray(value) ? value : [value]\n      for (const child of children) {\n        if (!child || typeof child !== 'object') continue\n        const childNode = child as TSESTree.Node\n        if (typeof childNode.type !== 'string') continue\n        // Do not descend into nested function scopes — their calls belong to a different context.\n        if (isFunctionNode(childNode)) continue\n        recurse(childNode)\n      }\n    }\n  }\n  recurse(body)\n}\n\n// A sub-agent is run through one of two blessed entry points: constructing a scoped\n// `new TurnRunner(...)`, or the lower-level static `DispatchRunner.dispatch(...)` (its constructor\n// is token-gated private, so `dispatch()` is the real entry point). Either one inside a tool handler\n// means \"this tool is deliberately a sub-agent,\" which is the documented exception to\n// no-model-in-tool-handler.\nconst isSubAgentEntry = (node: TSESTree.Node): boolean => {\n  // new TurnRunner(...)\n  if (\n    node.type === 'NewExpression' &&\n    node.callee.type === 'Identifier' &&\n    node.callee.name === 'TurnRunner'\n  ) {\n    return true\n  }\n  // DispatchRunner.dispatch(...)\n  if (\n    node.type === 'CallExpression' &&\n    node.callee.type === 'MemberExpression' &&\n    node.callee.property.type === 'Identifier' &&\n    node.callee.property.name === 'dispatch' &&\n    node.callee.object.type === 'Identifier' &&\n    node.callee.object.name === 'DispatchRunner'\n  ) {\n    return true\n  }\n  return false\n}\n\n/**\n * True when the function body runs a scoped sub-agent — either `new TurnRunner(...)` or\n * `DispatchRunner.dispatch(...)` — the documented escape hatch that exempts a tool handler from\n * {@link isLlmCall} flagging.\n */\nexport const runsSubAgent = (body: TSESTree.Node): boolean => {\n  let found = false\n  const recurse = (node: TSESTree.Node): void => {\n    if (found) return\n    if (isSubAgentEntry(node)) {\n      found = true\n      return\n    }\n    for (const key of Object.keys(node)) {\n      if (key === 'parent') continue\n      const value = (node as unknown as Record<string, unknown>)[key]\n      const children = Array.isArray(value) ? value : [value]\n      for (const child of children) {\n        if (!child || typeof child !== 'object') continue\n        const childNode = child as TSESTree.Node\n        if (typeof childNode.type !== 'string') continue\n        recurse(childNode)\n      }\n    }\n  }\n  recurse(body)\n  return found\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAmBA,IAAa,+CAAa,EAAA,YAAY,aACnC,SAAS,mCAAmC,MAC/C;AAQA,IAAa,kBAAkB,SAC7B,KAAK,SAAS,yBACd,KAAK,SAAS,wBACd,KAAK,SAAS;AAIhB,IAAM,iBAAiB,IAAI,IAAI;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAID,IAAM,mBAAmB,IAAI,IAAI;CAAC;CAAmB;CAAyB;AAAiB,CAAC;AAEhG,IAAM,sBAAsB,SAC1B,KAAK,SAAS,SAAS,eAAe,KAAK,SAAS,OAAO,KAAA;;;;;;;AAQ7D,IAAa,aAAa,SAAiC;CACzD,IAAI,KAAK,SAAS,iBAChB,OAAO,KAAK,OAAO,SAAS,gBAAgB,eAAe,IAAI,KAAK,OAAO,IAAI;CAEjF,IAAI,KAAK,SAAS,oBAAoB,KAAK,OAAO,SAAS,oBAAoB;EAC7E,MAAM,SAAS,mBAAmB,KAAK,MAAM;EAC7C,IAAI,UAAU,iBAAiB,IAAI,MAAM,GAAG,OAAO;EAEnD,IAAI,WAAW,UAAU;GACvB,IAAI,MAAqB,KAAK,OAAO;GACrC,OAAO,IAAI,SAAS,oBAAoB;IACtC,MAAM,MAAM,mBAAmB,GAAG;IAClC,IAAI,QAAQ,iBAAiB,QAAQ,cAAc,QAAQ,aAAa,OAAO;IAC/E,MAAM,IAAI;GACZ;EACF;CACF;CACA,OAAO;AACT;;;;;;AAOA,IAAa,mCACX,MACA,UACS;CACT,MAAM,WAAW,SAA8B;EAC7C,MAAM,IAAI;EACV,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,GAAG;GACnC,IAAI,QAAQ,UAAU;GACtB,MAAM,QAAS,KAA4C;GAC3D,MAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;GACtD,KAAK,MAAM,SAAS,UAAU;IAC5B,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU;IACzC,MAAM,YAAY;IAClB,IAAI,OAAO,UAAU,SAAS,UAAU;IAExC,IAAI,eAAe,SAAS,GAAG;IAC/B,QAAQ,SAAS;GACnB;EACF;CACF;CACA,QAAQ,IAAI;AACd;AAOA,IAAM,mBAAmB,SAAiC;CAExD,IACE,KAAK,SAAS,mBACd,KAAK,OAAO,SAAS,gBACrB,KAAK,OAAO,SAAS,cAErB,OAAO;CAGT,IACE,KAAK,SAAS,oBACd,KAAK,OAAO,SAAS,sBACrB,KAAK,OAAO,SAAS,SAAS,gBAC9B,KAAK,OAAO,SAAS,SAAS,cAC9B,KAAK,OAAO,OAAO,SAAS,gBAC5B,KAAK,OAAO,OAAO,SAAS,kBAE5B,OAAO;CAET,OAAO;AACT;;;;;;AAOA,IAAa,gBAAgB,SAAiC;CAC5D,IAAI,QAAQ;CACZ,MAAM,WAAW,SAA8B;EAC7C,IAAI,OAAO;EACX,IAAI,gBAAgB,IAAI,GAAG;GACzB,QAAQ;GACR;EACF;EACA,KAAK,MAAM,OAAO,OAAO,KAAK,IAAI,GAAG;GACnC,IAAI,QAAQ,UAAU;GACtB,MAAM,QAAS,KAA4C;GAC3D,MAAM,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;GACtD,KAAK,MAAM,SAAS,UAAU;IAC5B,IAAI,CAAC,SAAS,OAAO,UAAU,UAAU;IACzC,MAAM,YAAY;IAClB,IAAI,OAAO,UAAU,SAAS,UAAU;IACxC,QAAQ,SAAS;GACnB;EACF;CACF;CACA,QAAQ,IAAI;CACZ,OAAO;AACT"}

package/eslint/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module @nhtio/adk/eslint
+ *
+ * The `@nhtio/adk` ESLint plugin: machine-checkable enforcement of the harness contracts that
+ * implementors of bring-your-own batteries, tools, and primitives are most likely to get wrong.
+ *
+ * @remarks
+ * These rules turn documented footguns into lint errors. They are report-only (no autofix) — each
+ * names the contract it enforces and the fix; carve out a deliberate exception with an inline
+ * `// eslint-disable-next-line adk/<rule> -- <reason>` comment.
+ *
+ * `@typescript-eslint/utils` and `eslint` are OPTIONAL peer dependencies of `@nhtio/adk` — installed
+ * only by consumers who lint with this plugin. The main library never imports this module.
+ *
+ * @example Flat config
+ * ```ts
+ * import adk from '@nhtio/adk/eslint'
+ *
+ * export default [
+ *   { plugins: { adk: adk.plugin }, rules: adk.configs.recommended.rules },
+ * ]
+ * ```
+ */
+import type { FlatConfig } from '@typescript-eslint/utils/ts-eslint';
+/**
+ * Map of rule id (without the `adk/` plugin prefix) to its rule object. Registered on the plugin as
+ * `rules`, so configs reference them as `adk/<id>`.
+ */
+export declare const rules: {
+    'require-validator-any-required': import("@typescript-eslint/utils/ts-eslint").RuleModule<"declareIntent", [
+    ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+    'no-model-in-tool-handler': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noModelInHandler", [
+    ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+    'thought-payload-requires-replay-tag': import("@typescript-eslint/utils/ts-eslint").RuleModule<"requireReplayTag", [
+    ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+    'token-encoding-requires-context-window': import("@typescript-eslint/utils/ts-eslint").RuleModule<"requireContextWindow", [
+    ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+    'artifact-tool-forbids-artifact-constructor': import("@typescript-eslint/utils/ts-eslint").RuleModule<"forbidArtifactConstructor", [
+    ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+        name: string;
+    };
+};
+/**
+ * The ESLint plugin object. Register under the `adk` namespace: `plugins: { adk: plugin }`.
+ */
+export declare const plugin: FlatConfig.Plugin;
+/**
+ * Named config presets. `recommended` enables every rule at `error` and registers the plugin under
+ * the `adk` namespace — spread it into a flat config to adopt the full set.
+ */
+export declare const configs: {
+    recommended: {
+        name: string;
+        plugins: {
+            adk: FlatConfig.Plugin;
+        };
+        rules: Partial<Record<string, import("@typescript-eslint/utils/ts-eslint").SharedConfig.RuleEntry>>;
+    };
+};
+/**
+ * Default export bundles the plugin and its config presets, mirroring the shape ESLint flat configs
+ * expect from a plugin module.
+ */
+declare const _default: {
+    plugin: FlatConfig.Plugin;
+    rules: {
+        'require-validator-any-required': import("@typescript-eslint/utils/ts-eslint").RuleModule<"declareIntent", [
+        ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'no-model-in-tool-handler': import("@typescript-eslint/utils/ts-eslint").RuleModule<"noModelInHandler", [
+        ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'thought-payload-requires-replay-tag': import("@typescript-eslint/utils/ts-eslint").RuleModule<"requireReplayTag", [
+        ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'token-encoding-requires-context-window': import("@typescript-eslint/utils/ts-eslint").RuleModule<"requireContextWindow", [
+        ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+        'artifact-tool-forbids-artifact-constructor': import("@typescript-eslint/utils/ts-eslint").RuleModule<"forbidArtifactConstructor", [
+        ], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+            name: string;
+        };
+    };
+    configs: {
+        recommended: {
+            name: string;
+            plugins: {
+                adk: FlatConfig.Plugin;
+            };
+            rules: Partial<Record<string, import("@typescript-eslint/utils/ts-eslint").SharedConfig.RuleEntry>>;
+        };
+    };
+};
+export default _default;

package/eslint/rules/artifact_tool_forbids_artifact_constructor.cjs

@@ -0,0 +1,57 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+require("../../chunk-Ble4zEEl.js");
+const require_common = require("../../common-DeNipTQI.js");
+//#region src/eslint/rules/artifact_tool_forbids_artifact_constructor.ts
+/**
+* @module @nhtio/adk/eslint/rules/artifact_tool_forbids_artifact_constructor
+*
+* Flags `new ArtifactTool({ … })` whose options literal sets an `artifactConstructor`.
+*
+* Why: an `ArtifactTool` is the tool that answers queries AGAINST a spooled artifact — it must not
+* itself return a `SpooledArtifact`, or the result would be re-wrapped into another artifact whose
+* query tools are themselves `ArtifactTool`s, and so on without end. The base `RawTool` accepts an
+* `artifactConstructor` (the subclass used to wrap a tool's bytes), but `ArtifactTool` explicitly
+* FORBIDS it (`artifactConstructor: validator.any().forbidden()` in its schema). Supplying one is a
+* recursion footgun the constructor rejects at runtime; this rule surfaces it at the construction
+* site so it fails lint.
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var isUndefinedValue = (node) => node.type === "Identifier" && node.name === "undefined";
+var artifactToolForbidsArtifactConstructorRule = require_common.createRule({
+	name: "artifact-tool-forbids-artifact-constructor",
+	meta: {
+		type: "problem",
+		docs: { description: "An `ArtifactTool` must not declare `artifactConstructor` — it answers queries against an artifact and cannot itself return one (infinite re-wrapping). The ArtifactTool schema forbids the field at runtime; this surfaces it at the construction site." },
+		schema: [],
+		messages: { forbidArtifactConstructor: "`new ArtifactTool` must not set `artifactConstructor` — an artifact-query tool cannot itself return a SpooledArtifact (it would re-wrap forever). The ArtifactTool schema forbids this field. Remove it. Opt out with an eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "ArtifactTool") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			for (const p of arg.properties) {
+				if (p.type === "SpreadElement") continue;
+				if (literalKey(p) === "artifactConstructor" && !isUndefinedValue(p.value)) context.report({
+					node: p,
+					messageId: "forbidArtifactConstructor"
+				});
+			}
+		} };
+	}
+});
+//#endregion
+exports.default = artifactToolForbidsArtifactConstructorRule;
+
+//# sourceMappingURL=artifact_tool_forbids_artifact_constructor.cjs.map

package/eslint/rules/artifact_tool_forbids_artifact_constructor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact_tool_forbids_artifact_constructor.cjs","names":[],"sources":["../../../src/eslint/rules/artifact_tool_forbids_artifact_constructor.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/artifact_tool_forbids_artifact_constructor\n *\n * Flags `new ArtifactTool({ … })` whose options literal sets an `artifactConstructor`.\n *\n * Why: an `ArtifactTool` is the tool that answers queries AGAINST a spooled artifact — it must not\n * itself return a `SpooledArtifact`, or the result would be re-wrapped into another artifact whose\n * query tools are themselves `ArtifactTool`s, and so on without end. The base `RawTool` accepts an\n * `artifactConstructor` (the subclass used to wrap a tool's bytes), but `ArtifactTool` explicitly\n * FORBIDS it (`artifactConstructor: validator.any().forbidden()` in its schema). Supplying one is a\n * recursion footgun the constructor rejects at runtime; this rule surfaces it at the construction\n * site so it fails lint.\n *\n * Opt-out:\n *   // eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor -- <reason>\n */\n\nimport { createRule } from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\nconst literalKey = (prop: TSESTree.Property): string | undefined => {\n  if (prop.computed) return undefined\n  if (prop.key.type === 'Identifier') return prop.key.name\n  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value\n  return undefined\n}\n\nconst isUndefinedValue = (node: TSESTree.Node): boolean =>\n  node.type === 'Identifier' && node.name === 'undefined'\n\nconst artifactToolForbidsArtifactConstructorRule = createRule({\n  name: 'artifact-tool-forbids-artifact-constructor',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'An `ArtifactTool` must not declare `artifactConstructor` — it answers queries against an artifact and cannot itself return one (infinite re-wrapping). The ArtifactTool schema forbids the field at runtime; this surfaces it at the construction site.',\n    },\n    schema: [],\n    messages: {\n      forbidArtifactConstructor:\n        '`new ArtifactTool` must not set `artifactConstructor` — an artifact-query tool cannot itself return a SpooledArtifact (it would re-wrap forever). The ArtifactTool schema forbids this field. Remove it. Opt out with an eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor comment + reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      NewExpression(node: TSESTree.NewExpression) {\n        if (node.callee.type !== 'Identifier' || node.callee.name !== 'ArtifactTool') return\n        const arg = node.arguments[0]\n        if (!arg || arg.type !== 'ObjectExpression') return\n\n        for (const p of arg.properties) {\n          if (p.type === 'SpreadElement') continue\n          if (literalKey(p) === 'artifactConstructor' && !isUndefinedValue(p.value)) {\n            context.report({ node: p, messageId: 'forbidArtifactConstructor' })\n          }\n        }\n      },\n    }\n  },\n})\n\nexport default artifactToolForbidsArtifactConstructorRule\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqBA,IAAM,cAAc,SAAgD;CAClE,IAAI,KAAK,UAAU,OAAO,KAAA;CAC1B,IAAI,KAAK,IAAI,SAAS,cAAc,OAAO,KAAK,IAAI;CACpD,IAAI,KAAK,IAAI,SAAS,aAAa,OAAO,KAAK,IAAI,UAAU,UAAU,OAAO,KAAK,IAAI;AAEzF;AAEA,IAAM,oBAAoB,SACxB,KAAK,SAAS,gBAAgB,KAAK,SAAS;AAE9C,IAAM,6CAA6C,eAAA,WAAW;CAC5D,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,0PACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,2BACE,qTACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,cAAc,MAA8B;GAC1C,IAAI,KAAK,OAAO,SAAS,gBAAgB,KAAK,OAAO,SAAS,gBAAgB;GAC9E,MAAM,MAAM,KAAK,UAAU;GAC3B,IAAI,CAAC,OAAO,IAAI,SAAS,oBAAoB;GAE7C,KAAK,MAAM,KAAK,IAAI,YAAY;IAC9B,IAAI,EAAE,SAAS,iBAAiB;IAChC,IAAI,WAAW,CAAC,MAAM,yBAAyB,CAAC,iBAAiB,EAAE,KAAK,GACtE,QAAQ,OAAO;KAAE,MAAM;KAAG,WAAW;IAA4B,CAAC;GAEtE;EACF,EACF;CACF;AACF,CAAC"}

package/eslint/rules/artifact_tool_forbids_artifact_constructor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module @nhtio/adk/eslint/rules/artifact_tool_forbids_artifact_constructor
+ *
+ * Flags `new ArtifactTool({ … })` whose options literal sets an `artifactConstructor`.
+ *
+ * Why: an `ArtifactTool` is the tool that answers queries AGAINST a spooled artifact — it must not
+ * itself return a `SpooledArtifact`, or the result would be re-wrapped into another artifact whose
+ * query tools are themselves `ArtifactTool`s, and so on without end. The base `RawTool` accepts an
+ * `artifactConstructor` (the subclass used to wrap a tool's bytes), but `ArtifactTool` explicitly
+ * FORBIDS it (`artifactConstructor: validator.any().forbidden()` in its schema). Supplying one is a
+ * recursion footgun the constructor rejects at runtime; this rule surfaces it at the construction
+ * site so it fails lint.
+ *
+ * Opt-out:
+ *   // eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor -- <reason>
+ */
+declare const artifactToolForbidsArtifactConstructorRule: import("@typescript-eslint/utils/ts-eslint").RuleModule<"forbidArtifactConstructor", [
+], unknown, import("@typescript-eslint/utils/ts-eslint").RuleListener> & {
+    name: string;
+};
+export default artifactToolForbidsArtifactConstructorRule;

package/eslint/rules/artifact_tool_forbids_artifact_constructor.mjs

@@ -0,0 +1,52 @@
+import { t as createRule } from "../../common-BUIjZ6LV.mjs";
+//#region src/eslint/rules/artifact_tool_forbids_artifact_constructor.ts
+/**
+* @module @nhtio/adk/eslint/rules/artifact_tool_forbids_artifact_constructor
+*
+* Flags `new ArtifactTool({ … })` whose options literal sets an `artifactConstructor`.
+*
+* Why: an `ArtifactTool` is the tool that answers queries AGAINST a spooled artifact — it must not
+* itself return a `SpooledArtifact`, or the result would be re-wrapped into another artifact whose
+* query tools are themselves `ArtifactTool`s, and so on without end. The base `RawTool` accepts an
+* `artifactConstructor` (the subclass used to wrap a tool's bytes), but `ArtifactTool` explicitly
+* FORBIDS it (`artifactConstructor: validator.any().forbidden()` in its schema). Supplying one is a
+* recursion footgun the constructor rejects at runtime; this rule surfaces it at the construction
+* site so it fails lint.
+*
+* Opt-out:
+*   // eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor -- <reason>
+*/
+var literalKey = (prop) => {
+	if (prop.computed) return void 0;
+	if (prop.key.type === "Identifier") return prop.key.name;
+	if (prop.key.type === "Literal" && typeof prop.key.value === "string") return prop.key.value;
+};
+var isUndefinedValue = (node) => node.type === "Identifier" && node.name === "undefined";
+var artifactToolForbidsArtifactConstructorRule = createRule({
+	name: "artifact-tool-forbids-artifact-constructor",
+	meta: {
+		type: "problem",
+		docs: { description: "An `ArtifactTool` must not declare `artifactConstructor` — it answers queries against an artifact and cannot itself return one (infinite re-wrapping). The ArtifactTool schema forbids the field at runtime; this surfaces it at the construction site." },
+		schema: [],
+		messages: { forbidArtifactConstructor: "`new ArtifactTool` must not set `artifactConstructor` — an artifact-query tool cannot itself return a SpooledArtifact (it would re-wrap forever). The ArtifactTool schema forbids this field. Remove it. Opt out with an eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor comment + reason." }
+	},
+	defaultOptions: [],
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || node.callee.name !== "ArtifactTool") return;
+			const arg = node.arguments[0];
+			if (!arg || arg.type !== "ObjectExpression") return;
+			for (const p of arg.properties) {
+				if (p.type === "SpreadElement") continue;
+				if (literalKey(p) === "artifactConstructor" && !isUndefinedValue(p.value)) context.report({
+					node: p,
+					messageId: "forbidArtifactConstructor"
+				});
+			}
+		} };
+	}
+});
+//#endregion
+export { artifactToolForbidsArtifactConstructorRule as default };
+
+//# sourceMappingURL=artifact_tool_forbids_artifact_constructor.mjs.map

package/eslint/rules/artifact_tool_forbids_artifact_constructor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact_tool_forbids_artifact_constructor.mjs","names":[],"sources":["../../../src/eslint/rules/artifact_tool_forbids_artifact_constructor.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/eslint/rules/artifact_tool_forbids_artifact_constructor\n *\n * Flags `new ArtifactTool({ … })` whose options literal sets an `artifactConstructor`.\n *\n * Why: an `ArtifactTool` is the tool that answers queries AGAINST a spooled artifact — it must not\n * itself return a `SpooledArtifact`, or the result would be re-wrapped into another artifact whose\n * query tools are themselves `ArtifactTool`s, and so on without end. The base `RawTool` accepts an\n * `artifactConstructor` (the subclass used to wrap a tool's bytes), but `ArtifactTool` explicitly\n * FORBIDS it (`artifactConstructor: validator.any().forbidden()` in its schema). Supplying one is a\n * recursion footgun the constructor rejects at runtime; this rule surfaces it at the construction\n * site so it fails lint.\n *\n * Opt-out:\n *   // eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor -- <reason>\n */\n\nimport { createRule } from './common'\n\nimport type { TSESTree } from '@typescript-eslint/utils'\n\nconst literalKey = (prop: TSESTree.Property): string | undefined => {\n  if (prop.computed) return undefined\n  if (prop.key.type === 'Identifier') return prop.key.name\n  if (prop.key.type === 'Literal' && typeof prop.key.value === 'string') return prop.key.value\n  return undefined\n}\n\nconst isUndefinedValue = (node: TSESTree.Node): boolean =>\n  node.type === 'Identifier' && node.name === 'undefined'\n\nconst artifactToolForbidsArtifactConstructorRule = createRule({\n  name: 'artifact-tool-forbids-artifact-constructor',\n  meta: {\n    type: 'problem',\n    docs: {\n      description:\n        'An `ArtifactTool` must not declare `artifactConstructor` — it answers queries against an artifact and cannot itself return one (infinite re-wrapping). The ArtifactTool schema forbids the field at runtime; this surfaces it at the construction site.',\n    },\n    schema: [],\n    messages: {\n      forbidArtifactConstructor:\n        '`new ArtifactTool` must not set `artifactConstructor` — an artifact-query tool cannot itself return a SpooledArtifact (it would re-wrap forever). The ArtifactTool schema forbids this field. Remove it. Opt out with an eslint-disable-next-line adk/artifact-tool-forbids-artifact-constructor comment + reason.',\n    },\n  },\n  defaultOptions: [],\n  create(context) {\n    return {\n      NewExpression(node: TSESTree.NewExpression) {\n        if (node.callee.type !== 'Identifier' || node.callee.name !== 'ArtifactTool') return\n        const arg = node.arguments[0]\n        if (!arg || arg.type !== 'ObjectExpression') return\n\n        for (const p of arg.properties) {\n          if (p.type === 'SpreadElement') continue\n          if (literalKey(p) === 'artifactConstructor' && !isUndefinedValue(p.value)) {\n            context.report({ node: p, messageId: 'forbidArtifactConstructor' })\n          }\n        }\n      },\n    }\n  },\n})\n\nexport default artifactToolForbidsArtifactConstructorRule\n"],"mappings":";;;;;;;;;;;;;;;;;;AAqBA,IAAM,cAAc,SAAgD;CAClE,IAAI,KAAK,UAAU,OAAO,KAAA;CAC1B,IAAI,KAAK,IAAI,SAAS,cAAc,OAAO,KAAK,IAAI;CACpD,IAAI,KAAK,IAAI,SAAS,aAAa,OAAO,KAAK,IAAI,UAAU,UAAU,OAAO,KAAK,IAAI;AAEzF;AAEA,IAAM,oBAAoB,SACxB,KAAK,SAAS,gBAAgB,KAAK,SAAS;AAE9C,IAAM,6CAA6C,WAAW;CAC5D,MAAM;CACN,MAAM;EACJ,MAAM;EACN,MAAM,EACJ,aACE,0PACJ;EACA,QAAQ,CAAC;EACT,UAAU,EACR,2BACE,qTACJ;CACF;CACA,gBAAgB,CAAC;CACjB,OAAO,SAAS;EACd,OAAO,EACL,cAAc,MAA8B;GAC1C,IAAI,KAAK,OAAO,SAAS,gBAAgB,KAAK,OAAO,SAAS,gBAAgB;GAC9E,MAAM,MAAM,KAAK,UAAU;GAC3B,IAAI,CAAC,OAAO,IAAI,SAAS,oBAAoB;GAE7C,KAAK,MAAM,KAAK,IAAI,YAAY;IAC9B,IAAI,EAAE,SAAS,iBAAiB;IAChC,IAAI,WAAW,CAAC,MAAM,yBAAyB,CAAC,iBAAiB,EAAE,KAAK,GACtE,QAAQ,OAAO;KAAE,MAAM;KAAG,WAAW;IAA4B,CAAC;GAEtE;EACF,EACF;CACF;AACF,CAAC"}

package/eslint/rules/common.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared `createRule` factory for the published `@nhtio/adk` ESLint rules.
+ *
+ * @remarks
+ * Wraps `ESLintUtils.RuleCreator` so every rule gets a consistent `meta.docs.url` pointing at the
+ * published rule reference. Each rule module imports this and default-exports `createRule({...})`.
+ *
+ * `@typescript-eslint/utils` is an OPTIONAL peer dependency of `@nhtio/adk` — it is only needed by
+ * consumers who import `@nhtio/adk/eslint`. The main library never imports this module.
+ */
+import { ESLintUtils } from '@typescript-eslint/utils';
+import type { TSESTree } from '@typescript-eslint/utils';
+/**
+ * Rule factory for `@nhtio/adk` ESLint rules. The `name` passed to each rule becomes the slug in the
+ * generated documentation URL.
+ */
+export declare const createRule: <Options extends readonly unknown[], MessageIds extends string>({ meta, name, ...rule }: Readonly<ESLintUtils.RuleWithMetaAndName<Options, MessageIds, unknown>>) => ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/** Any function-like AST node (arrow, function expression, or declaration). */
+export type FunctionNode = TSESTree.FunctionDeclaration | TSESTree.FunctionExpression | TSESTree.ArrowFunctionExpression;
+export declare const isFunctionNode: (node: TSESTree.Node) => node is FunctionNode;
+/**
+ * Heuristic: does this call/new expression look like a primary LLM invocation? Detects known
+ * provider SDK constructors and `…create()` calls whose receiver chain passes through
+ * `chat`/`completions`/`messages`/`responses`, plus a small set of generate* methods. Deliberately
+ * conservative — the goal is to catch the obvious footgun, not to be exhaustive.
+ */
+export declare const isLlmCall: (node: TSESTree.Node) => boolean;
+/**
+ * Walks the descendants of a function body (NOT crossing into nested function scopes) and invokes
+ * `visit` for every node, so a rule can scan a handler/middleware body for a pattern while ignoring
+ * inner closures (e.g. a `new TurnRunner` sub-agent's own callbacks).
+ */
+export declare const walkBodySkippingNestedFunctions: (body: TSESTree.Node, visit: (node: TSESTree.Node) => void) => void;
+/**
+ * True when the function body runs a scoped sub-agent — either `new TurnRunner(...)` or
+ * `DispatchRunner.dispatch(...)` — the documented escape hatch that exempts a tool handler from
+ * {@link isLlmCall} flagging.
+ */
+export declare const runsSubAgent: (body: TSESTree.Node) => boolean;