@flowy-agent-store/protocol 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/index.cjs

@@ -6,7 +6,32 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * The chat surface uses only opaque public conversation/message IDs. Internal
 * execution/session/step/attempt IDs never appear in this module.
 */
-const APP_SERVER_PROTOCOL_VERSION = "2026-08-26";
+/**
+* A contract **fingerprint**, not a version number: it must differ from the
+* previous value on any wire change at all, additive included. The shape is
+* `fp-<n>` — a plain counter, so a bump just increments it and no value is ever
+* reused by accident.
+*
+* So it is a **label, not a version**: neither a release number nor a date.
+* Until `fp-1` the values were date stamps (kept below as history), and those
+* dates were **not** the day of the change: consecutive changes advanced the
+* stamp a day each, so they ran ahead of the calendar. The list below is keyed
+* by *value* — read it as "which wire change is this?", never as "when did this
+* ship".
+*
+* `2026-09-16` carried `StoreItem.published_at`; `2026-09-17` added the two MCP
+* declaration write methods (`config/set-mcp`, `config/set-mcp-enabled`);
+* `2026-09-18` adds `config/get-mcp`, the file editor's read of the same file;
+* `2026-09-19` adds the `conversation/list-changed` notification; `2026-09-20`
+* adds the Skill **file tree** read face (`skill/files`, `skill/file`) so a
+* Skill's companion files are readable, not just its bounded manifest summary;
+* `2026-09-21` adds the connector **call proxy** (`connector/call`), so a third
+* party can run an installed MCP tool while the connection and its credentials
+* stay on the host. **`fp-1` changes the shape only** (date stamp → counter): a
+* `2026-…` value invites being read as a release date, and no wire behaviour
+* changed with the rename.
+*/
+const APP_SERVER_PROTOCOL_VERSION = "fp-1";
 //#endregion
 //#region src/errors.ts
 var AppServerError = class extends Error {
@@ -78,12 +103,352 @@ function isRetryableError(error) {
 	return (error instanceof AppServerError || error instanceof TransportError) && error.retryable;
 }
 //#endregion
+//#region src/localized.ts
+/** The other language, i.e. the second link of every fallback chain. */
+function otherLocalizedLang(lang) {
+	return lang === "zh" ? "en" : "zh";
+}
+/**
+* Map an i18n language tag (`zh-CN`, `en-US`, `en`) to a variant language.
+* Anything that is not English resolves to `zh`, matching the app default.
+*/
+function toLocalizedLang(language) {
+	return (language ?? "").toLowerCase().startsWith("en") ? "en" : "zh";
+}
+/** `{field}_{lang}` → `{field}_{other}` → `""`. */
+function pickLocalized(text, lang) {
+	if (!text) return "";
+	return text[lang]?.trim() || text[otherLocalizedLang(lang)]?.trim() || "";
+}
+/** Resolve a list of localized values, dropping the ones that resolve empty. */
+function pickLocalizedList(list, lang) {
+	return (list ?? []).map((item) => pickLocalized(item, lang)).filter((value) => value.length > 0);
+}
+/** Non-empty string variants in fallback order. */
+function variantKeys(field, lang) {
+	return [`${field}_${lang}`, `${field}_${otherLocalizedLang(lang)}`];
+}
+/** `{field}_{lang}` → `{field}_{other}` as a string, when either carries text. */
+function pickVariantText(variants, field, lang) {
+	for (const key of variantKeys(field, lang)) {
+		const value = variants?.[key];
+		if (typeof value === "string" && value.trim().length > 0) return value;
+	}
+}
+/** `{field}_{lang}` → `{field}_{other}` as a string list, when either is non-empty. */
+function pickVariantList(variants, field, lang) {
+	for (const key of variantKeys(field, lang)) {
+		const value = variants?.[key];
+		if (Array.isArray(value)) {
+			const items = value.filter((item) => typeof item === "string" && item.length > 0);
+			if (items.length > 0) return items;
+		}
+	}
+}
+/**
+* Market entry tags. Per D8=A `tags_{lang}` outranks `legacy_tags_{lang}` —
+* the legacy field only fills in when the current one is absent, in either
+* language.
+*/
+function pickEntryTags(variants, lang) {
+	return pickVariantList(variants, "tags", lang) ?? pickVariantList(variants, "legacy_tags", lang);
+}
+/**
+* A market entry text field: variant first, then the baseline field
+* (`entry.description`, `entry.name`, …) as the last link of the chain.
+*/
+function pickEntryText(variants, field, lang, baseline) {
+	return pickVariantText(variants, field, lang) ?? baseline ?? void 0;
+}
+//#endregion
+//#region src/conversation-events.ts
+function stringValue(value) {
+	return typeof value === "string" ? value : null;
+}
+function numberValue(value) {
+	return typeof value === "number" ? value : null;
+}
+function isRecord(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Strict boolean reader: a wire value that is not a real boolean reads as
+* `null` (unknown) rather than being coerced — "retryable" must never be
+* guessed from a truthy string.
+*/
+function booleanValue(value) {
+	return typeof value === "boolean" ? value : null;
+}
+/** Flatten a message/activity body to plain text, JSON-encoding anything else. */
+function contentToText(value) {
+	if (typeof value === "string") return value;
+	if (isRecord(value) && typeof value.content === "string") return value.content;
+	return value == null ? "" : JSON.stringify(value);
+}
+/** Activity bodies may be nested one level down or JSON-encoded as a string. */
+function unwrapContent(value) {
+	if (typeof value === "string") try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+	if (isRecord(value)) {
+		const content = value.content;
+		if (typeof content === "string") try {
+			return JSON.parse(content);
+		} catch {
+			return value;
+		}
+	}
+	return value;
+}
+/** Shape a thinking body (`message.thinking`, or `message.activity` kind `thinking`). */
+function thinkingData(value) {
+	if (isRecord(value) && typeof value.content === "string") return {
+		content: value.content,
+		subject: stringValue(value.subject),
+		status: stringValue(value.status),
+		duration: numberValue(value.duration) ?? numberValue(value.duration_ms)
+	};
+	const candidate = unwrapContent(value);
+	if (!isRecord(candidate)) return {
+		content: typeof candidate === "string" ? candidate : "",
+		subject: null,
+		status: null,
+		duration: null
+	};
+	return {
+		content: stringValue(candidate.content) ?? "",
+		subject: stringValue(candidate.subject),
+		status: stringValue(candidate.status),
+		duration: numberValue(candidate.duration) ?? numberValue(candidate.duration_ms)
+	};
+}
+/** Shape a tips body; `type` is accepted as an alias of `tip_type`. */
+function tipsData(value) {
+	const readTip = (data) => {
+		const content = stringValue(data.content);
+		const tipType = stringValue(data.tip_type) ?? stringValue(data.type);
+		if (content === null && tipType === null) return null;
+		return {
+			content: content ?? "",
+			tipType: tipType ?? "info"
+		};
+	};
+	if (isRecord(value)) {
+		const direct = readTip(value);
+		if (direct) return direct;
+	}
+	const candidate = unwrapContent(value);
+	if (isRecord(candidate)) {
+		const parsed = readTip(candidate);
+		if (parsed) return parsed;
+	}
+	if (candidate != null && !isRecord(candidate)) return {
+		content: String(candidate),
+		tipType: "info"
+	};
+	return {
+		content: "",
+		tipType: "info"
+	};
+}
+/** Shape a tool-call body; `null` when the body carries nothing tool-shaped. */
+function toolCallData(value) {
+	const candidate = unwrapContent(value);
+	if (!isRecord(candidate)) return null;
+	const name = stringValue(candidate.name) ?? stringValue(candidate.tool_name) ?? stringValue(candidate.tool);
+	if (!name && candidate.args === void 0 && candidate.arguments === void 0 && candidate.output === void 0 && candidate.result === void 0) return null;
+	return {
+		name,
+		args: candidate.args ?? candidate.arguments ?? candidate.input,
+		output: candidate.output ?? candidate.result,
+		status: stringValue(candidate.status)
+	};
+}
+/**
+* Shape a plan body; `null` when there is no usable step list.
+*
+* `step` is accepted as an alias of `content`: the tool's own argument is named
+* `step`, and the producer normalizes it to `content` for the plan row — a row
+* written before that normalization (or by a producer that skipped it) would
+* otherwise render as an empty plan.
+*/
+function planData(value) {
+	const candidate = unwrapContent(value);
+	if (!isRecord(candidate) || !Array.isArray(candidate.entries)) return null;
+	const entries = candidate.entries.flatMap((raw) => {
+		if (!isRecord(raw)) return [];
+		const content = stringValue(raw.content) ?? stringValue(raw.step);
+		if (!content) return [];
+		return [{
+			content,
+			status: planStepStatus(raw.status)
+		}];
+	});
+	return entries.length > 0 ? { entries } : null;
+}
+/** Unknown/absent step statuses read as `pending` — never as "done". */
+function planStepStatus(value) {
+	return value === "completed" || value === "in_progress" ? value : "pending";
+}
+/** Shape a `context.usage` payload; `null` when nothing was actually measured. */
+function parseContextUsage(value) {
+	if (!isRecord(value)) return null;
+	const used = typeof value.used_tokens === "number" ? value.used_tokens : 0;
+	const window = typeof value.window_tokens === "number" ? value.window_tokens : 0;
+	if (used <= 0 || window <= 0) return null;
+	const rawPercent = typeof value.percent === "number" ? value.percent : used / window * 100;
+	return {
+		used_tokens: used,
+		window_tokens: window,
+		percent: Math.min(100, Math.max(0, rawPercent)),
+		updated_at: typeof value.updated_at === "number" ? value.updated_at : Date.now(),
+		source: typeof value.source === "string" ? value.source : "measured"
+	};
+}
+/**
+* Shape a per-turn `usage` body (W9 / R14); `null` when the runtime reported
+* nothing usable.
+*
+* A missing side is **unknown**, not zero: half a bill is not a bill, so a
+* frame that only carries `input_tokens` decodes to `null` rather than to a
+* total that silently drops the output side. Same rule for an all-zero report —
+* "no tokens reported" must never render as "this turn was free".
+*/
+function parseTurnUsage(value) {
+	if (!isRecord(value)) return null;
+	const input = typeof value.input_tokens === "number" ? value.input_tokens : null;
+	const output = typeof value.output_tokens === "number" ? value.output_tokens : null;
+	if (input === null || output === null) return null;
+	if (input <= 0 && output <= 0) return null;
+	return {
+		input_tokens: input,
+		output_tokens: output,
+		total_tokens: typeof value.total_tokens === "number" ? value.total_tokens : input + output
+	};
+}
+/**
+* Decode one `conversation/event` frame into a typed body.
+*
+* An activity frame whose `kind` is `thinking` is normalized to
+* `message.thinking` (the server has two spellings for the same thing).
+*/
+function decodeConversationEvent(event) {
+	const payload = event.payload ?? {};
+	const messageId = () => stringValue(payload.message_id);
+	const createdAt = () => numberValue(payload.created_at);
+	if (event.event_type === "message.activity" && stringValue(payload.kind) === "thinking") return {
+		kind: "message.thinking",
+		event,
+		messageId: messageId(),
+		createdAt: createdAt(),
+		thinking: thinkingData(payload),
+		replace: payload.replace === true
+	};
+	switch (event.event_type) {
+		case "message.created": return {
+			kind: "message.created",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			content: payload.content ?? ""
+		};
+		case "message.delta": return {
+			kind: "message.delta",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			delta: stringValue(payload.content) ?? "",
+			replace: payload.replace === true
+		};
+		case "message.thinking": return {
+			kind: "message.thinking",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			thinking: thinkingData(payload),
+			replace: payload.replace === true
+		};
+		case "message.tool": return {
+			kind: "message.tool",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			tool: toolCallData(payload)
+		};
+		case "message.tips": return {
+			kind: "message.tips",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			tips: tipsData(payload)
+		};
+		case "message.error": return {
+			kind: "message.error",
+			event,
+			messageId: messageId(),
+			createdAt: createdAt(),
+			message: stringValue(payload.message),
+			code: stringValue(payload.code),
+			retryable: booleanValue(payload.retryable)
+		};
+		case "message.activity": {
+			const activityKind = stringValue(payload.kind) ?? "activity";
+			return {
+				kind: "message.activity",
+				event,
+				messageId: messageId(),
+				createdAt: createdAt(),
+				activityKind,
+				content: payload.content ?? "",
+				usage: activityKind === "turn_completed" ? parseTurnUsage(payload.usage) : null
+			};
+		}
+		case "turn.status": return {
+			kind: "turn.status",
+			event,
+			running: stringValue(payload.status) === "running"
+		};
+		case "context.usage": return {
+			kind: "context.usage",
+			event,
+			usage: parseContextUsage(payload.context_usage)
+		};
+		default: return {
+			kind: "unknown",
+			event,
+			eventType: event.event_type
+		};
+	}
+}
+//#endregion
 exports.APP_SERVER_PROTOCOL_VERSION = APP_SERVER_PROTOCOL_VERSION;
 exports.AppServerError = AppServerError;
 exports.ProtocolError = ProtocolError;
 exports.RequestTimeoutError = RequestTimeoutError;
 exports.TransportError = TransportError;
+exports.booleanValue = booleanValue;
+exports.contentToText = contentToText;
+exports.decodeConversationEvent = decodeConversationEvent;
 exports.formatError = formatError;
 exports.isAppServerError = isAppServerError;
+exports.isRecord = isRecord;
 exports.isRetryableError = isRetryableError;
 exports.isRetryableTransportError = isRetryableTransportError;
+exports.numberValue = numberValue;
+exports.otherLocalizedLang = otherLocalizedLang;
+exports.parseContextUsage = parseContextUsage;
+exports.parseTurnUsage = parseTurnUsage;
+exports.pickEntryTags = pickEntryTags;
+exports.pickEntryText = pickEntryText;
+exports.pickLocalized = pickLocalized;
+exports.pickLocalizedList = pickLocalizedList;
+exports.pickVariantList = pickVariantList;
+exports.pickVariantText = pickVariantText;
+exports.planData = planData;
+exports.stringValue = stringValue;
+exports.thinkingData = thinkingData;
+exports.tipsData = tipsData;
+exports.toLocalizedLang = toLocalizedLang;
+exports.toolCallData = toolCallData;