@tangle-network/sdk-provider-cli-base 0.0.0-stage → 0.13.0

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2025 Tangle Network
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of this Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+Tangle Network.
+
+For licensing inquiries, contact: hello@tangle.tools

package/dist/conformance/index.d.mts

@@ -0,0 +1,79 @@
+import { i as PreparedAttachment } from "../prompt-input-BHn_1z69.mjs";
+import { StreamEvent } from "@tangle-network/agent-interface";
+
+//#region src/conformance/attachments.d.ts
+/**
+ * Asserts an adapter delivered `attachment` as a native input part: one of
+ * its `path`, `base64`, or `url` appears verbatim in argv or stdin, AND the
+ * fallback marker appears in neither — a native delivery that also leaves
+ * the marker behind would describe the same image to the model twice, once
+ * as a real input part and once as a dangling text reference.
+ */
+declare function assertImageForwardedNatively(input: {
+  args: string[];
+  stdin?: string;
+  attachment: PreparedAttachment;
+}): void;
+/**
+ * Asserts an adapter left `attachment` on the marker-only fallback path: its
+ * `[Image: <ref>]` / `[File: <ref>]` marker text appears in argv or stdin —
+ * i.e. it locks that the adapter actually DELIVERS the marker-bearing prompt
+ * to the CLI, not merely that the marker exists somewhere upstream of
+ * `buildExecArgs`. This is the contract for every adapter that does not opt
+ * the attachment's kind into `nativeAttachmentKinds()`: a future native
+ * opt-in that suppresses the marker without ever wiring up native delivery
+ * reds this instead of silently downgrading to an undelivered fallback.
+ */
+declare function assertImageMarkerFallback(input: {
+  args: string[];
+  stdin?: string;
+  attachment: PreparedAttachment;
+}): void;
+//#endregion
+//#region src/conformance/scenarios.d.ts
+type ScenarioName = /** One reasoning block, delivered however the provider natively does. */"reasoning-single-block" /** Two distinct reasoning blocks → two part ids, correct texts, in order. */ | "reasoning-two-blocks" /** One block streamed as increments → one id, append-only deltas. */ | "reasoning-streamed-deltas" /** Same content delivered twice (stream + final message) → no duplicate parts. */ | "reasoning-snapshot-replay" /** Plain text output → one text part id, correct final text. */ | "text-single-part" /** Text and reasoning interleaved → ids never collide across types. */ | "text-interleaved-reasoning" /** A tool call → tool part with callID and full-snapshot input. */ | "tool-call-basic" /** A write-tool call surfaces a file part with a stable id and URL. */ | "file-part-from-write-tool";
+interface ScenarioExpectation {
+  /** Final text of each distinct reasoning block, in emission order. */
+  reasoningBlockTexts?: string[];
+  /**
+   * Every reasoning update must carry a delta (default true). Set false only
+   * for adapters whose provider genuinely re-snapshots without increments.
+   */
+  reasoningDeltasRequired?: boolean;
+  /** Final text-part content. */
+  finalText?: string;
+  /** Tool calls that must appear, with their final full-snapshot input. */
+  toolCalls?: Array<{
+    callID: string;
+    input: unknown;
+  }>;
+  /** File parts that must appear, keyed by final {url, mediaType}. */
+  fileParts?: Array<{
+    url: string;
+    mediaType?: string;
+  }>;
+}
+interface ScenarioResult {
+  events: StreamEvent[];
+  expected: ScenarioExpectation;
+}
+/** Scenario-level checks on top of `assertStreamInvariants`. */
+declare function assertScenarioExpectations(name: ScenarioName, result: ScenarioResult): void;
+//#endregion
+//#region src/conformance/binding.d.ts
+type ScenarioRunner = () => ScenarioResult | Promise<ScenarioResult>;
+interface ConformanceBinding {
+  /** Adapter name, for test titles and failure messages. */
+  adapter: string;
+  /** Only the scenarios this provider's event shape supports. */
+  scenarios: Partial<Record<ScenarioName, ScenarioRunner>>;
+}
+/** Typed entries of a binding's declared scenarios. */
+declare function conformanceScenarioEntries(binding: ConformanceBinding): Array<[ScenarioName, ScenarioRunner]>;
+//#endregion
+//#region src/conformance/invariants.d.ts
+/** Replays a trace and throws listing every invariant violation found. */
+declare function assertStreamInvariants(events: StreamEvent[]): void;
+//#endregion
+export { type ConformanceBinding, type ScenarioExpectation, type ScenarioName, type ScenarioResult, type ScenarioRunner, assertImageForwardedNatively, assertImageMarkerFallback, assertScenarioExpectations, assertStreamInvariants, conformanceScenarioEntries };
+//# sourceMappingURL=index.d.mts.map

package/dist/conformance/index.mjs

@@ -0,0 +1,192 @@
+//#region src/conformance/attachments.ts
+/** True when `needle` appears verbatim in one argv element or in stdin.
+*  Checked per-element (never joined) so a match can never straddle two
+*  unrelated argv entries. */
+function appearsInArgsOrStdin(input, needle) {
+	if (input.args.some((arg) => arg.includes(needle))) return true;
+	return (input.stdin ?? "").includes(needle);
+}
+/**
+* Asserts an adapter delivered `attachment` as a native input part: one of
+* its `path`, `base64`, or `url` appears verbatim in argv or stdin, AND the
+* fallback marker appears in neither — a native delivery that also leaves
+* the marker behind would describe the same image to the model twice, once
+* as a real input part and once as a dangling text reference.
+*/
+function assertImageForwardedNatively(input) {
+	const { attachment } = input;
+	const candidates = [
+		attachment.path,
+		attachment.base64,
+		attachment.url
+	].filter((value) => value !== void 0);
+	if (candidates.length === 0) throw new Error("assertImageForwardedNatively: attachment carries none of path/base64/url — nothing to check native delivery against");
+	if (!candidates.some((candidate) => appearsInArgsOrStdin(input, candidate))) throw new Error(`assertImageForwardedNatively: none of the attachment's path/base64/url (${candidates.length} candidate(s)) appear in argv or stdin — the attachment was not forwarded natively`);
+	if (appearsInArgsOrStdin(input, attachment.marker)) throw new Error(`assertImageForwardedNatively: fallback marker ${JSON.stringify(attachment.marker)} found in argv or stdin alongside the native delivery — a native path must not also leave the text marker behind`);
+}
+/**
+* Asserts an adapter left `attachment` on the marker-only fallback path: its
+* `[Image: <ref>]` / `[File: <ref>]` marker text appears in argv or stdin —
+* i.e. it locks that the adapter actually DELIVERS the marker-bearing prompt
+* to the CLI, not merely that the marker exists somewhere upstream of
+* `buildExecArgs`. This is the contract for every adapter that does not opt
+* the attachment's kind into `nativeAttachmentKinds()`: a future native
+* opt-in that suppresses the marker without ever wiring up native delivery
+* reds this instead of silently downgrading to an undelivered fallback.
+*/
+function assertImageMarkerFallback(input) {
+	const { attachment } = input;
+	if (!appearsInArgsOrStdin(input, attachment.marker)) throw new Error(`assertImageMarkerFallback: fallback marker ${JSON.stringify(attachment.marker)} not found in argv or stdin`);
+}
+//#endregion
+//#region src/conformance/binding.ts
+/** Typed entries of a binding's declared scenarios. */
+function conformanceScenarioEntries(binding) {
+	return Object.entries(binding.scenarios).filter((entry) => entry[1] !== void 0);
+}
+//#endregion
+//#region src/conformance/invariants.ts
+const STATUS_RANK = {
+	pending: 0,
+	running: 1,
+	completed: 2,
+	failed: 2,
+	error: 2
+};
+function isPartUpdate(event) {
+	return event.type === "message.part.updated";
+}
+/** Replays a trace and throws listing every invariant violation found. */
+function assertStreamInvariants(events) {
+	const errors = [];
+	const tracks = /* @__PURE__ */ new Map();
+	const textIdsByMessage = /* @__PURE__ */ new Map();
+	events.forEach((event, index) => {
+		if (!isPartUpdate(event)) return;
+		const part = event.part;
+		const at = `event[${index}] part "${part.id}"`;
+		if (!part.id) {
+			errors.push(`event[${index}]: part id is empty`);
+			return;
+		}
+		const prev = tracks.get(part.id);
+		if (prev && prev.type !== part.type) {
+			errors.push(`${at}: type changed "${prev.type}" -> "${part.type}"`);
+			return;
+		}
+		if (prev && prev.messageID !== part.messageID) errors.push(`${at}: messageID changed "${prev.messageID}" -> "${part.messageID}"`);
+		const track = prev ?? {
+			type: part.type,
+			messageID: part.messageID,
+			text: "",
+			sawDelta: false
+		};
+		if (part.type === "text" || part.type === "reasoning") {
+			const text = part.text;
+			if (event.delta !== void 0) {
+				if (track.text + event.delta !== text) errors.push(`${at}: delta is not an append-only suffix (prev ${JSON.stringify(track.text)} + delta ${JSON.stringify(event.delta)} !== text ${JSON.stringify(text)})`);
+				track.sawDelta = true;
+			} else {
+				if (track.sawDelta && text !== track.text) errors.push(`${at}: mixed update modes — earlier updates carried a delta, this one changes text without one`);
+				if (!text.startsWith(track.text)) errors.push(`${at}: snapshot rewrites earlier content (prev ${JSON.stringify(track.text)}, got ${JSON.stringify(text)})`);
+			}
+			track.text = text;
+			if (part.type === "text") {
+				const ids = textIdsByMessage.get(part.messageID) ?? /* @__PURE__ */ new Set();
+				ids.add(part.id);
+				textIdsByMessage.set(part.messageID, ids);
+				if (ids.size > 1) errors.push(`${at}: message "${part.messageID}" has ${ids.size} text part ids (expected one)`);
+			}
+		}
+		if (part.type === "tool") {
+			if (!part.callID) errors.push(`${at}: tool part is missing callID`);
+			else if (track.callID !== void 0 && track.callID !== part.callID) errors.push(`${at}: callID changed "${track.callID}" -> "${part.callID}"`);
+			track.callID = part.callID;
+			if (part.state?.input === void 0) errors.push(`${at}: tool update is missing the full input snapshot`);
+			const rank = STATUS_RANK[part.state?.status];
+			if (rank === void 0) errors.push(`${at}: unknown tool status "${part.state?.status}"`);
+			else {
+				if (track.statusRank !== void 0 && rank < track.statusRank) errors.push(`${at}: tool status regressed to "${part.state.status}"`);
+				track.statusRank = rank;
+			}
+		}
+		if (part.type === "file") {
+			if (event.delta !== void 0) errors.push(`${at}: file part carries a delta (file parts are snapshot-only)`);
+			if (!part.url) errors.push(`${at}: file part is missing a non-empty url`);
+			else if (track.fileUrl !== void 0 && track.fileUrl !== part.url) errors.push(`${at}: file url changed "${track.fileUrl}" -> "${part.url}"`);
+			if (part.url) track.fileUrl = part.url;
+		}
+		tracks.set(part.id, track);
+	});
+	if (errors.length > 0) throw new Error(`stream invariants violated (${errors.length}):\n- ${errors.join("\n- ")}`);
+}
+//#endregion
+//#region src/conformance/scenarios.ts
+function partUpdates(events) {
+	return events.filter((e) => e.type === "message.part.updated");
+}
+/** Final text per part id of the given type, in first-appearance order. */
+function finalTextsByPartId(events, type) {
+	const texts = /* @__PURE__ */ new Map();
+	for (const event of partUpdates(events)) {
+		if (event.part.type !== type) continue;
+		texts.set(event.part.id, event.part.text);
+	}
+	return texts;
+}
+/** Scenario-level checks on top of `assertStreamInvariants`. */
+function assertScenarioExpectations(name, result) {
+	const errors = [];
+	const { events, expected } = result;
+	if (expected.reasoningBlockTexts) {
+		const finals = finalTextsByPartId(events, "reasoning");
+		const got = [...finals.values()];
+		if (got.length !== expected.reasoningBlockTexts.length) errors.push(`expected ${expected.reasoningBlockTexts.length} distinct reasoning part id(s), got ${got.length} (${JSON.stringify([...finals.keys()])})`);
+		else expected.reasoningBlockTexts.forEach((text, i) => {
+			if (got[i] !== text) errors.push(`reasoning block ${i}: expected ${JSON.stringify(text)}, got ${JSON.stringify(got[i])}`);
+		});
+	}
+	if (expected.reasoningDeltasRequired ?? true) partUpdates(events).forEach((event, i) => {
+		if (event.part.type === "reasoning" && event.delta === void 0) errors.push(`reasoning update ${i} for part "${event.part.id}" carries no delta`);
+	});
+	if (expected.finalText !== void 0) {
+		const finals = [...finalTextsByPartId(events, "text").values()];
+		if (finals.length !== 1 || finals[0] !== expected.finalText) errors.push(`expected one text part with final text ${JSON.stringify(expected.finalText)}, got ${JSON.stringify(finals)}`);
+	}
+	if (expected.toolCalls) for (const call of expected.toolCalls) {
+		const updates = partUpdates(events).filter((e) => e.part.type === "tool" && e.part.callID === call.callID);
+		const last = updates[updates.length - 1];
+		if (!last || last.part.type !== "tool") {
+			errors.push(`no tool part with callID "${call.callID}"`);
+			continue;
+		}
+		const gotInput = JSON.stringify(last.part.state.input);
+		const wantInput = JSON.stringify(call.input);
+		if (gotInput !== wantInput) errors.push(`tool "${call.callID}": final input ${gotInput} !== expected ${wantInput}`);
+	}
+	if (expected.fileParts) {
+		const fileUpdates = partUpdates(events).filter((e) => e.part.type === "file");
+		const idsByUrl = /* @__PURE__ */ new Map();
+		const finalByPartId = /* @__PURE__ */ new Map();
+		for (const event of fileUpdates) {
+			if (event.part.type !== "file") continue;
+			const url = event.part.url ?? "";
+			const ids = idsByUrl.get(url) ?? /* @__PURE__ */ new Set();
+			ids.add(event.part.id);
+			idsByUrl.set(url, ids);
+			finalByPartId.set(event.part.id, {
+				url,
+				mediaType: event.part.mediaType
+			});
+		}
+		for (const [url, ids] of idsByUrl) if (ids.size > 1) errors.push(`file part url ${JSON.stringify(url)} has ${ids.size} distinct part ids (expected exactly one — dedupe failed)`);
+		const finals = [...finalByPartId.values()];
+		if (finals.length !== expected.fileParts.length) errors.push(`expected ${expected.fileParts.length} distinct file part id(s), got ${finals.length} (${JSON.stringify(finals)})`);
+		else for (const want of expected.fileParts) if (!finals.some((got) => got.url === want.url && got.mediaType === want.mediaType)) errors.push(`no file part with final state ${JSON.stringify(want)} (got ${JSON.stringify(finals)})`);
+	}
+	if (errors.length > 0) throw new Error(`scenario "${name}" expectations failed (${errors.length}):\n- ${errors.join("\n- ")}`);
+}
+//#endregion
+export { assertImageForwardedNatively, assertImageMarkerFallback, assertScenarioExpectations, assertStreamInvariants, conformanceScenarioEntries };
+
+//# sourceMappingURL=index.mjs.map