@graphorin/provider 0.5.0

package/dist/reasoning/retention.js

@@ -0,0 +1,33 @@
+//#region src/reasoning/retention.ts
+/**
+* Map from `ReasoningContract` to the conservative default
+* `ReasoningRetention` value used when no override is supplied.
+*
+* @stable
+*/
+const REASONING_RETENTION_DEFAULTS = Object.freeze({
+	hidden: "strip",
+	"round-trip-required": "pass-through-claude",
+	optional: "strip"
+});
+/**
+* Resolve the effective {@link ReasoningRetention} value for a single
+* request. The resolution is precedence-driven:
+*
+* 1. `requested` wins if defined.
+* 2. `overridden` wins next.
+* 3. The default for `contract` is used if the contract is known.
+* 4. `'strip'` is the conservative fallback when no input is supplied.
+*
+* @stable
+*/
+function resolveReasoningRetention(input) {
+	if (input.requested !== void 0) return input.requested;
+	if (input.overridden !== void 0) return input.overridden;
+	if (input.contract !== void 0) return REASONING_RETENTION_DEFAULTS[input.contract];
+	return "strip";
+}
+
+//#endregion
+export { REASONING_RETENTION_DEFAULTS, resolveReasoningRetention };
+//# sourceMappingURL=retention.js.map

package/dist/reasoning/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","names":["REASONING_RETENTION_DEFAULTS: Readonly<Record<ReasoningContract, ReasoningRetention>>"],"sources":["../../src/reasoning/retention.ts"],"sourcesContent":["/**\n * Reasoning-retention resolver — picks the effective\n * {@link ReasoningRetention} value for a request given:\n *\n * 1. an explicit per-request `reasoningRetention` field (highest\n *    precedence — user override always wins),\n * 2. an instance-level override supplied to `createProvider({...})`,\n *    and\n * 3. the auto-detected default derived from the adapter's declared\n *    `capabilities.reasoningContract` (lowest precedence).\n *\n * @packageDocumentation\n */\n\nimport type { ReasoningContract, ReasoningRetention } from '@graphorin/core';\n\n/**\n * Map from `ReasoningContract` to the conservative default\n * `ReasoningRetention` value used when no override is supplied.\n *\n * @stable\n */\nexport const REASONING_RETENTION_DEFAULTS: Readonly<Record<ReasoningContract, ReasoningRetention>> =\n  Object.freeze({\n    hidden: 'strip',\n    'round-trip-required': 'pass-through-claude',\n    optional: 'strip',\n  });\n\n/**\n * Inputs to {@link resolveReasoningRetention}.\n *\n * @stable\n */\nexport interface ResolveReasoningRetentionInput {\n  /** Explicit per-request override (highest precedence). */\n  readonly requested?: ReasoningRetention;\n  /** Instance-level override supplied to `createProvider({...})`. */\n  readonly overridden?: ReasoningRetention;\n  /** Adapter-declared capability (lowest precedence). */\n  readonly contract?: ReasoningContract;\n}\n\n/**\n * Resolve the effective {@link ReasoningRetention} value for a single\n * request. The resolution is precedence-driven:\n *\n * 1. `requested` wins if defined.\n * 2. `overridden` wins next.\n * 3. The default for `contract` is used if the contract is known.\n * 4. `'strip'` is the conservative fallback when no input is supplied.\n *\n * @stable\n */\nexport function resolveReasoningRetention(\n  input: ResolveReasoningRetentionInput,\n): ReasoningRetention {\n  if (input.requested !== undefined) return input.requested;\n  if (input.overridden !== undefined) return input.overridden;\n  if (input.contract !== undefined) {\n    return REASONING_RETENTION_DEFAULTS[input.contract];\n  }\n  return 'strip';\n}\n"],"mappings":";;;;;;;AAsBA,MAAaA,+BACX,OAAO,OAAO;CACZ,QAAQ;CACR,uBAAuB;CACvB,UAAU;CACX,CAAC;;;;;;;;;;;;AA2BJ,SAAgB,0BACd,OACoB;AACpB,KAAI,MAAM,cAAc,OAAW,QAAO,MAAM;AAChD,KAAI,MAAM,eAAe,OAAW,QAAO,MAAM;AACjD,KAAI,MAAM,aAAa,OACrB,QAAO,6BAA6B,MAAM;AAE5C,QAAO"}

package/dist/tool-examples.d.ts

@@ -0,0 +1,14 @@
+import { ToolDefinition } from "@graphorin/core";
+
+//#region src/tool-examples.d.ts
+
+/**
+ * Fold each tool's `examples` into its `description` and drop the structured
+ * field. Non-destructive: a tool with no examples is returned by reference, and
+ * the whole array is returned unchanged (same reference) when nothing folds — so
+ * callers can cheaply detect a no-op.
+ */
+declare function foldToolExamples(tools: ReadonlyArray<ToolDefinition>): ReadonlyArray<ToolDefinition>;
+//#endregion
+export { foldToolExamples };
+//# sourceMappingURL=tool-examples.d.ts.map

package/dist/tool-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-examples.d.ts","names":[],"sources":["../src/tool-examples.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;iBA8BgB,gBAAA,QACP,cAAc,kBACpB,cAAc"}

package/dist/tool-examples.js

@@ -0,0 +1,35 @@
+//#region src/tool-examples.ts
+/** Render worked examples as a compact, deterministic text block. */
+function renderExamplesSection(examples) {
+	return `Examples:\n${examples.map((ex, i) => {
+		const comment = ex.comment !== void 0 ? `  // ${ex.comment}` : "";
+		return `${i + 1}. input: ${JSON.stringify(ex.input)} -> output: ${JSON.stringify(ex.output)}${comment}`;
+	}).join("\n")}`;
+}
+/**
+* Fold each tool's `examples` into its `description` and drop the structured
+* field. Non-destructive: a tool with no examples is returned by reference, and
+* the whole array is returned unchanged (same reference) when nothing folds — so
+* callers can cheaply detect a no-op.
+*/
+function foldToolExamples(tools) {
+	let changed = false;
+	const out = tools.map((tool) => {
+		const examples = tool.examples;
+		if (examples === void 0 || examples.length === 0) return tool;
+		changed = true;
+		const section = renderExamplesSection(examples);
+		const description = tool.description !== void 0 && tool.description.length > 0 ? `${tool.description}\n\n${section}` : section;
+		return {
+			name: tool.name,
+			inputSchema: tool.inputSchema,
+			description,
+			...tool.outputSchema !== void 0 ? { outputSchema: tool.outputSchema } : {}
+		};
+	});
+	return changed ? out : tools;
+}
+
+//#endregion
+export { foldToolExamples };
+//# sourceMappingURL=tool-examples.js.map

package/dist/tool-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-examples.js","names":[],"sources":["../src/tool-examples.ts"],"sourcesContent":["/**\n * A1 (SOTA): fold a tool's worked `examples` into its model-facing description.\n *\n * `ToolDefinition` already carries `examples` on the wire (the agent projects\n * them from `Tool.examples`), and the contract notes implementations MAY fold\n * them into the description — but no adapter did, so the model never saw them.\n * Anthropic reports complex-parameter accuracy jumps 72% → 90% with worked\n * examples in the tool text. This renders them deterministically (so the tool\n * spec stays prompt-cache-stable) and drops the now-redundant structured field.\n *\n * @packageDocumentation\n */\n\nimport type { ToolDefinition, ToolDefinitionExample } from '@graphorin/core';\n\n/** Render worked examples as a compact, deterministic text block. */\nfunction renderExamplesSection(examples: ReadonlyArray<ToolDefinitionExample>): string {\n  const lines = examples.map((ex, i) => {\n    const comment = ex.comment !== undefined ? `  // ${ex.comment}` : '';\n    return `${i + 1}. input: ${JSON.stringify(ex.input)} -> output: ${JSON.stringify(ex.output)}${comment}`;\n  });\n  return `Examples:\\n${lines.join('\\n')}`;\n}\n\n/**\n * Fold each tool's `examples` into its `description` and drop the structured\n * field. Non-destructive: a tool with no examples is returned by reference, and\n * the whole array is returned unchanged (same reference) when nothing folds — so\n * callers can cheaply detect a no-op.\n */\nexport function foldToolExamples(\n  tools: ReadonlyArray<ToolDefinition>,\n): ReadonlyArray<ToolDefinition> {\n  let changed = false;\n  const out = tools.map((tool): ToolDefinition => {\n    const examples = tool.examples;\n    if (examples === undefined || examples.length === 0) return tool;\n    changed = true;\n    const section = renderExamplesSection(examples);\n    const description =\n      tool.description !== undefined && tool.description.length > 0\n        ? `${tool.description}\\n\\n${section}`\n        : section;\n    // Rebuild without `examples` (now in the description text), preserving every\n    // other field — notably `outputSchema` (A5).\n    return {\n      name: tool.name,\n      inputSchema: tool.inputSchema,\n      description,\n      ...(tool.outputSchema !== undefined ? { outputSchema: tool.outputSchema } : {}),\n    };\n  });\n  return changed ? out : tools;\n}\n"],"mappings":";;AAgBA,SAAS,sBAAsB,UAAwD;AAKrF,QAAO,cAJO,SAAS,KAAK,IAAI,MAAM;EACpC,MAAM,UAAU,GAAG,YAAY,SAAY,QAAQ,GAAG,YAAY;AAClE,SAAO,GAAG,IAAI,EAAE,WAAW,KAAK,UAAU,GAAG,MAAM,CAAC,cAAc,KAAK,UAAU,GAAG,OAAO,GAAG;GAC9F,CACyB,KAAK,KAAK;;;;;;;;AASvC,SAAgB,iBACd,OAC+B;CAC/B,IAAI,UAAU;CACd,MAAM,MAAM,MAAM,KAAK,SAAyB;EAC9C,MAAM,WAAW,KAAK;AACtB,MAAI,aAAa,UAAa,SAAS,WAAW,EAAG,QAAO;AAC5D,YAAU;EACV,MAAM,UAAU,sBAAsB,SAAS;EAC/C,MAAM,cACJ,KAAK,gBAAgB,UAAa,KAAK,YAAY,SAAS,IACxD,GAAG,KAAK,YAAY,MAAM,YAC1B;AAGN,SAAO;GACL,MAAM,KAAK;GACX,aAAa,KAAK;GAClB;GACA,GAAI,KAAK,iBAAiB,SAAY,EAAE,cAAc,KAAK,cAAc,GAAG,EAAE;GAC/E;GACD;AACF,QAAO,UAAU,MAAM"}

package/dist/trust/classify-local-provider.d.ts

@@ -0,0 +1,47 @@
+import { LocalProviderTrust, Sensitivity } from "@graphorin/core";
+
+//#region src/trust/classify-local-provider.d.ts
+
+/**
+ * Result of {@link classifyLocalProvider}. Carries both the trust
+ * class and a short human-readable reason for the WARN log produced
+ * by the consuming adapter.
+ *
+ * @stable
+ */
+interface LocalProviderClassification {
+  readonly trust: LocalProviderTrust;
+  /** One-line reason — `'loopback IP 127.0.0.1'`, `'public IP 5.6.7.8 over HTTPS'`, ... */
+  readonly reason: string;
+  /** Default `acceptsSensitivity` for this trust class. */
+  readonly acceptsSensitivity: ReadonlyArray<Sensitivity>;
+}
+/**
+ * Per-tier default sensitivity envelope. Lifted to a constant so
+ * downstream code (and tests) can import it without re-deriving the
+ * matrix.
+ *
+ * @stable
+ */
+declare const SENSITIVITY_DEFAULTS_PER_TRUST: Readonly<Record<LocalProviderTrust, ReadonlyArray<Sensitivity>>>;
+/**
+ * Classify a URL string into one of the four {@link LocalProviderTrust}
+ * tiers. Throws `TypeError` if the URL is unparseable so adapters
+ * fail fast at construction time (programming error; not a runtime
+ * fault).
+ *
+ * @stable
+ */
+declare function classifyLocalProvider(baseUrl: string): LocalProviderClassification;
+/**
+ * Permanent loopback classification used by in-process adapters
+ * (e.g. the `llamaCppNodeAdapter` companion package). Adapters that
+ * have no `baseUrl` declare this directly to make the source-of-truth
+ * symmetry obvious.
+ *
+ * @stable
+ */
+declare const PERMANENT_LOOPBACK_CLASSIFICATION: LocalProviderClassification;
+//#endregion
+export { LocalProviderClassification, PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider };
+//# sourceMappingURL=classify-local-provider.d.ts.map

package/dist/trust/classify-local-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-local-provider.d.ts","names":[],"sources":["../../src/trust/classify-local-provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;UA8BiB,2BAAA;kBACC;;;;+BAIa,cAAc;;;;;;;;;cAUhC,gCAAgC,SAC3C,OAAO,oBAAoB,cAAc;;;;;;;;;iBAgB3B,qBAAA,mBAAwC;;;;;;;;;cA2L3C,mCAAmC"}

package/dist/trust/classify-local-provider.js

@@ -0,0 +1,164 @@
+//#region src/trust/classify-local-provider.ts
+/**
+* Per-tier default sensitivity envelope. Lifted to a constant so
+* downstream code (and tests) can import it without re-deriving the
+* matrix.
+*
+* @stable
+*/
+const SENSITIVITY_DEFAULTS_PER_TRUST = Object.freeze({
+	loopback: Object.freeze([
+		"public",
+		"internal",
+		"secret"
+	]),
+	private: Object.freeze(["public", "internal"]),
+	"public-tls": Object.freeze(["public"]),
+	"public-cleartext": Object.freeze([])
+});
+/**
+* Classify a URL string into one of the four {@link LocalProviderTrust}
+* tiers. Throws `TypeError` if the URL is unparseable so adapters
+* fail fast at construction time (programming error; not a runtime
+* fault).
+*
+* @stable
+*/
+function classifyLocalProvider(baseUrl) {
+	if (typeof baseUrl !== "string" || baseUrl.length === 0) throw new TypeError("classifyLocalProvider: baseUrl must be a non-empty string.");
+	if (baseUrl.startsWith("unix://") || baseUrl.startsWith("unix:/")) return {
+		trust: "loopback",
+		reason: `unix domain socket (${baseUrl})`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback
+	};
+	let url;
+	try {
+		url = new URL(baseUrl);
+	} catch (cause) {
+		throw new TypeError(`classifyLocalProvider: baseUrl '${baseUrl}' is not a valid URL.`, { cause });
+	}
+	const protocol = url.protocol;
+	const hostname = url.hostname;
+	if (protocol !== "http:" && protocol !== "https:") return {
+		trust: "private",
+		reason: `non-HTTP protocol '${protocol}'`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private
+	};
+	const ipv4 = parseIpv4(hostname);
+	if (ipv4 !== null) {
+		if (isLoopbackIpv4(ipv4)) return {
+			trust: "loopback",
+			reason: `loopback IPv4 ${hostname}`,
+			acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback
+		};
+		if (isPrivateIpv4(ipv4)) return {
+			trust: "private",
+			reason: `private IPv4 ${hostname}`,
+			acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private
+		};
+		return classifyPublic(protocol, `public IPv4 ${hostname}`);
+	}
+	if (isIpv6(hostname)) {
+		if (isLoopbackIpv6(hostname)) return {
+			trust: "loopback",
+			reason: `loopback IPv6 ${hostname}`,
+			acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback
+		};
+		if (isPrivateIpv6(hostname)) return {
+			trust: "private",
+			reason: `private IPv6 ${hostname}`,
+			acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private
+		};
+		return classifyPublic(protocol, `public IPv6 ${hostname}`);
+	}
+	if (isLoopbackHostname(hostname)) return {
+		trust: "loopback",
+		reason: `loopback hostname '${hostname}'`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback
+	};
+	if (isPrivateHostnameSuffix(hostname)) return {
+		trust: "private",
+		reason: `private hostname suffix '${hostname}'`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private
+	};
+	return classifyPublic(protocol, `public hostname '${hostname}'`);
+}
+function classifyPublic(protocol, reason) {
+	if (protocol === "https:") return {
+		trust: "public-tls",
+		reason: `${reason} over HTTPS`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST["public-tls"]
+	};
+	return {
+		trust: "public-cleartext",
+		reason: `${reason} over HTTP`,
+		acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST["public-cleartext"]
+	};
+}
+function parseIpv4(hostname) {
+	const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
+	if (match === null) return null;
+	const a = Number(match[1]);
+	const b = Number(match[2]);
+	const c = Number(match[3]);
+	const d = Number(match[4]);
+	if (a > 255 || b > 255 || c > 255 || d > 255) return null;
+	return [
+		a,
+		b,
+		c,
+		d
+	];
+}
+function isLoopbackIpv4(ip) {
+	return ip[0] === 127;
+}
+function isPrivateIpv4(ip) {
+	if (ip[0] === 10) return true;
+	if (ip[0] === 192 && ip[1] === 168) return true;
+	if (ip[0] === 172 && ip[1] >= 16 && ip[1] <= 31) return true;
+	if (ip[0] === 100 && ip[1] >= 64 && ip[1] <= 127) return true;
+	if (ip[0] === 169 && ip[1] === 254) return true;
+	return false;
+}
+function isIpv6(hostname) {
+	return (hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname).includes(":");
+}
+function normaliseIpv6(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+function isLoopbackIpv6(hostname) {
+	const norm = normaliseIpv6(hostname).toLowerCase();
+	return norm === "::1" || norm === "0:0:0:0:0:0:0:1";
+}
+function isPrivateIpv6(hostname) {
+	const norm = normaliseIpv6(hostname).toLowerCase();
+	if (norm.startsWith("fe80:") || norm.startsWith("fe8") || norm.startsWith("fe9") || norm.startsWith("fea") || norm.startsWith("feb")) return true;
+	if (norm.startsWith("fc") || norm.startsWith("fd")) return true;
+	return false;
+}
+function isLoopbackHostname(hostname) {
+	const lower = hostname.toLowerCase();
+	return lower === "localhost" || lower === "localhost.";
+}
+function isPrivateHostnameSuffix(hostname) {
+	const lower = hostname.toLowerCase();
+	return lower.endsWith(".local") || lower.endsWith(".lan") || lower.endsWith(".internal") || lower.endsWith(".home.arpa") || lower.endsWith(".intranet");
+}
+/**
+* Permanent loopback classification used by in-process adapters
+* (e.g. the `llamaCppNodeAdapter` companion package). Adapters that
+* have no `baseUrl` declare this directly to make the source-of-truth
+* symmetry obvious.
+*
+* @stable
+*/
+const PERMANENT_LOOPBACK_CLASSIFICATION = Object.freeze({
+	trust: "loopback",
+	reason: "in-process adapter (no baseUrl)",
+	acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback
+});
+
+//#endregion
+export { PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider };
+//# sourceMappingURL=classify-local-provider.js.map

package/dist/trust/classify-local-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-local-provider.js","names":["SENSITIVITY_DEFAULTS_PER_TRUST: Readonly<\n  Record<LocalProviderTrust, ReadonlyArray<Sensitivity>>\n>","url: URL","PERMANENT_LOOPBACK_CLASSIFICATION: LocalProviderClassification"],"sources":["../../src/trust/classify-local-provider.ts"],"sourcesContent":["/**\n * Shared trust classifier for every `baseUrl`-driven local-LLM\n * adapter. Emits one of four discriminant values per\n * {@link LocalProviderTrust}:\n *\n * - `'loopback'`         — the URL points at the same host as the\n *   running process (`localhost`, `127.0.0.0/8`, `::1`, or a\n *   `unix:///path` socket).\n * - `'private'`          — RFC 1918 / RFC 6598 / link-local /\n *   multicast-DNS-style hostname.\n * - `'public-tls'`       — public host AND `https://`.\n * - `'public-cleartext'` — public host AND `http://`.\n *\n * The dispatcher is a pure function: it sees the URL string and\n * nothing else. DNS resolution is deferred to the adapter layer\n * (cross-cut DEC-149 § DNS-rebinding mitigation), where the resolved\n * IP is re-classified on TTL expiry and the lowest-trust value wins.\n *\n * @packageDocumentation\n */\n\nimport type { LocalProviderTrust, Sensitivity } from '@graphorin/core';\n\n/**\n * Result of {@link classifyLocalProvider}. Carries both the trust\n * class and a short human-readable reason for the WARN log produced\n * by the consuming adapter.\n *\n * @stable\n */\nexport interface LocalProviderClassification {\n  readonly trust: LocalProviderTrust;\n  /** One-line reason — `'loopback IP 127.0.0.1'`, `'public IP 5.6.7.8 over HTTPS'`, ... */\n  readonly reason: string;\n  /** Default `acceptsSensitivity` for this trust class. */\n  readonly acceptsSensitivity: ReadonlyArray<Sensitivity>;\n}\n\n/**\n * Per-tier default sensitivity envelope. Lifted to a constant so\n * downstream code (and tests) can import it without re-deriving the\n * matrix.\n *\n * @stable\n */\nexport const SENSITIVITY_DEFAULTS_PER_TRUST: Readonly<\n  Record<LocalProviderTrust, ReadonlyArray<Sensitivity>>\n> = Object.freeze({\n  loopback: Object.freeze(['public', 'internal', 'secret'] as const),\n  private: Object.freeze(['public', 'internal'] as const),\n  'public-tls': Object.freeze(['public'] as const),\n  'public-cleartext': Object.freeze([] as const),\n});\n\n/**\n * Classify a URL string into one of the four {@link LocalProviderTrust}\n * tiers. Throws `TypeError` if the URL is unparseable so adapters\n * fail fast at construction time (programming error; not a runtime\n * fault).\n *\n * @stable\n */\nexport function classifyLocalProvider(baseUrl: string): LocalProviderClassification {\n  if (typeof baseUrl !== 'string' || baseUrl.length === 0) {\n    throw new TypeError('classifyLocalProvider: baseUrl must be a non-empty string.');\n  }\n\n  if (baseUrl.startsWith('unix://') || baseUrl.startsWith('unix:/')) {\n    return {\n      trust: 'loopback',\n      reason: `unix domain socket (${baseUrl})`,\n      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,\n    };\n  }\n\n  let url: URL;\n  try {\n    url = new URL(baseUrl);\n  } catch (cause) {\n    throw new TypeError(`classifyLocalProvider: baseUrl '${baseUrl}' is not a valid URL.`, {\n      cause,\n    });\n  }\n\n  const protocol = url.protocol;\n  const hostname = url.hostname;\n  if (protocol !== 'http:' && protocol !== 'https:') {\n    // Custom protocols (e.g. ws://) are out of scope for the four\n    // bundled adapters; treat as private so a downstream WARN fires.\n    return {\n      trust: 'private',\n      reason: `non-HTTP protocol '${protocol}'`,\n      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,\n    };\n  }\n\n  const ipv4 = parseIpv4(hostname);\n  if (ipv4 !== null) {\n    if (isLoopbackIpv4(ipv4)) {\n      return {\n        trust: 'loopback',\n        reason: `loopback IPv4 ${hostname}`,\n        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,\n      };\n    }\n    if (isPrivateIpv4(ipv4)) {\n      return {\n        trust: 'private',\n        reason: `private IPv4 ${hostname}`,\n        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,\n      };\n    }\n    return classifyPublic(protocol, `public IPv4 ${hostname}`);\n  }\n\n  if (isIpv6(hostname)) {\n    if (isLoopbackIpv6(hostname)) {\n      return {\n        trust: 'loopback',\n        reason: `loopback IPv6 ${hostname}`,\n        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,\n      };\n    }\n    if (isPrivateIpv6(hostname)) {\n      return {\n        trust: 'private',\n        reason: `private IPv6 ${hostname}`,\n        acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,\n      };\n    }\n    return classifyPublic(protocol, `public IPv6 ${hostname}`);\n  }\n\n  if (isLoopbackHostname(hostname)) {\n    return {\n      trust: 'loopback',\n      reason: `loopback hostname '${hostname}'`,\n      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,\n    };\n  }\n  if (isPrivateHostnameSuffix(hostname)) {\n    return {\n      trust: 'private',\n      reason: `private hostname suffix '${hostname}'`,\n      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.private,\n    };\n  }\n\n  return classifyPublic(protocol, `public hostname '${hostname}'`);\n}\n\nfunction classifyPublic(protocol: string, reason: string): LocalProviderClassification {\n  if (protocol === 'https:') {\n    return {\n      trust: 'public-tls',\n      reason: `${reason} over HTTPS`,\n      acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST['public-tls'],\n    };\n  }\n  return {\n    trust: 'public-cleartext',\n    reason: `${reason} over HTTP`,\n    acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST['public-cleartext'],\n  };\n}\n\nfunction parseIpv4(hostname: string): [number, number, number, number] | null {\n  const match = /^(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})$/.exec(hostname);\n  if (match === null) return null;\n  const a = Number(match[1]);\n  const b = Number(match[2]);\n  const c = Number(match[3]);\n  const d = Number(match[4]);\n  if (a > 255 || b > 255 || c > 255 || d > 255) return null;\n  return [a, b, c, d];\n}\n\nfunction isLoopbackIpv4(ip: readonly [number, number, number, number]): boolean {\n  return ip[0] === 127;\n}\n\nfunction isPrivateIpv4(ip: readonly [number, number, number, number]): boolean {\n  // RFC 1918\n  if (ip[0] === 10) return true;\n  if (ip[0] === 192 && ip[1] === 168) return true;\n  if (ip[0] === 172 && ip[1] >= 16 && ip[1] <= 31) return true;\n  // RFC 6598 (CGNAT — Tailscale-friendly)\n  if (ip[0] === 100 && ip[1] >= 64 && ip[1] <= 127) return true;\n  // Link-local\n  if (ip[0] === 169 && ip[1] === 254) return true;\n  return false;\n}\n\nfunction isIpv6(hostname: string): boolean {\n  const stripped =\n    hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;\n  return stripped.includes(':');\n}\n\nfunction normaliseIpv6(hostname: string): string {\n  return hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname;\n}\n\nfunction isLoopbackIpv6(hostname: string): boolean {\n  const norm = normaliseIpv6(hostname).toLowerCase();\n  return norm === '::1' || norm === '0:0:0:0:0:0:0:1';\n}\n\nfunction isPrivateIpv6(hostname: string): boolean {\n  const norm = normaliseIpv6(hostname).toLowerCase();\n  // Link-local fe80::/10\n  if (\n    norm.startsWith('fe80:') ||\n    norm.startsWith('fe8') ||\n    norm.startsWith('fe9') ||\n    norm.startsWith('fea') ||\n    norm.startsWith('feb')\n  ) {\n    return true;\n  }\n  // Unique local fc00::/7 (covers fc:: and fd::)\n  if (norm.startsWith('fc') || norm.startsWith('fd')) return true;\n  return false;\n}\n\nfunction isLoopbackHostname(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n  return lower === 'localhost' || lower === 'localhost.';\n}\n\nfunction isPrivateHostnameSuffix(hostname: string): boolean {\n  const lower = hostname.toLowerCase();\n  return (\n    lower.endsWith('.local') ||\n    lower.endsWith('.lan') ||\n    lower.endsWith('.internal') ||\n    lower.endsWith('.home.arpa') ||\n    lower.endsWith('.intranet')\n  );\n}\n\n/**\n * Permanent loopback classification used by in-process adapters\n * (e.g. the `llamaCppNodeAdapter` companion package). Adapters that\n * have no `baseUrl` declare this directly to make the source-of-truth\n * symmetry obvious.\n *\n * @stable\n */\nexport const PERMANENT_LOOPBACK_CLASSIFICATION: LocalProviderClassification = Object.freeze({\n  trust: 'loopback',\n  reason: 'in-process adapter (no baseUrl)',\n  acceptsSensitivity: SENSITIVITY_DEFAULTS_PER_TRUST.loopback,\n});\n"],"mappings":"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"}

package/dist/trust/index.d.ts

@@ -0,0 +1,3 @@
+import { LocalProviderClassification, PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider } from "./classify-local-provider.js";
+import { LocalProviderTrust, OllamaTrust } from "@graphorin/core";
+export { type LocalProviderClassification, type LocalProviderTrust, type OllamaTrust, PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider };

package/dist/trust/index.js

@@ -0,0 +1,3 @@
+import { PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider } from "./classify-local-provider.js";
+
+export { PERMANENT_LOOPBACK_CLASSIFICATION, SENSITIVITY_DEFAULTS_PER_TRUST, classifyLocalProvider };

package/package.json

@@ -0,0 +1,128 @@
+{
+  "name": "@graphorin/provider",
+  "version": "0.5.0",
+  "description": "Vendor-neutral LLM provider layer for the Graphorin framework. Ships the canonical Provider interface, the Vercel AI SDK adapter (default cloud path), three local-LLM adapters (direct Ollama HTTP, llama-server HTTP, and a generic OpenAI-compatible adapter for LMStudio / LocalAI / vLLM / Together-style endpoints), the shared LocalProviderTrust classifier (loopback / private / public-tls / public-cleartext), the canonical-order middleware composer (withTracing / withRetry / withRateLimit / withCostLimit / withCostTracking / withFallback / withRedaction), the pluggable TokenCounter dispatcher (js-tiktoken default plus per-vendor native counters and a heuristic fallback), the per-provider model-tier auto-classifier (fast / balanced / smart), and the production startup hook that fails fast when withRedaction is missing.",
+  "license": "MIT",
+  "author": "Oleksiy Stepurenko",
+  "homepage": "https://github.com/o-stepper/graphorin/tree/main/packages/provider",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/graphorin.git",
+    "directory": "packages/provider"
+  },
+  "bugs": {
+    "url": "https://github.com/o-stepper/graphorin/issues"
+  },
+  "keywords": [
+    "graphorin",
+    "ai",
+    "agents",
+    "framework",
+    "provider",
+    "llm",
+    "vercel-ai-sdk",
+    "ollama",
+    "llama-cpp",
+    "openai-compatible",
+    "middleware",
+    "retry",
+    "fallback",
+    "rate-limit",
+    "cost-limit",
+    "redaction",
+    "token-counter",
+    "tiktoken",
+    "local-first"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapters/vercel": {
+      "types": "./dist/adapters/vercel.d.ts",
+      "import": "./dist/adapters/vercel.js"
+    },
+    "./adapters/ollama": {
+      "types": "./dist/adapters/ollama.d.ts",
+      "import": "./dist/adapters/ollama.js"
+    },
+    "./adapters/llamacpp-server": {
+      "types": "./dist/adapters/llamacpp-server.d.ts",
+      "import": "./dist/adapters/llamacpp-server.js"
+    },
+    "./adapters/openai-compatible": {
+      "types": "./dist/adapters/openai-compatible.d.ts",
+      "import": "./dist/adapters/openai-compatible.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js"
+    },
+    "./counters": {
+      "types": "./dist/counters/index.d.ts",
+      "import": "./dist/counters/index.js"
+    },
+    "./trust": {
+      "types": "./dist/trust/index.d.ts",
+      "import": "./dist/trust/index.js"
+    },
+    "./model-tier": {
+      "types": "./dist/model-tier/index.d.ts",
+      "import": "./dist/model-tier/index.js"
+    },
+    "./reasoning": {
+      "types": "./dist/reasoning/index.d.ts",
+      "import": "./dist/reasoning/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@graphorin/core": "0.5.0",
+    "@graphorin/observability": "0.5.0"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.0-beta.76",
+    "js-tiktoken": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "js-tiktoken": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.0",
+    "js-tiktoken": "^1.0.21"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "test": "vitest run",
+    "lint": "biome check .",
+    "clean": "rimraf dist .turbo *.tsbuildinfo"
+  }
+}