@flowy-agent-store/protocol 0.1.0-beta.10

package/dist/index.mjs

@@ -0,0 +1,481 @@
+//#region src/protocol.ts
+/**
+* Agent Store App Server Protocol types.
+*
+* The chat surface uses only opaque public conversation/message IDs. Internal
+* execution/session/step/attempt IDs never appear in this module.
+*/
+/**
+* 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. **`fp-2` carries the tools' parameters**
+* (`ConnectorTool.input_schema`, plus `tools_truncated` on `ConnectorDetail`
+* and `ConnectorProbeResult`): a caller that must *name* a tool to be granted it
+* should be able to read what that tool takes. It is the counterpart of the
+* host's `[connector_proxy]` grant moving from one tool at a time to the
+* connector (doc `26`). **`fp-3` makes a Skill selectable per turn**:
+* `conversation/send` gains an optional `mentions` list whose only honoured kind
+* is `skill`, so one turn can mount a Skill's instructions without rewriting the
+* conversation's create-time snapshot (doc `27` 阶段 1). **`fp-4` lets a
+* conversation be created as an installed expert**: `conversation/create` gains
+* an optional `agent_id`, whose Definition supplies the chat's preset identity
+* plus its own Skill and Connector fences — frozen at creation, since none of
+* those keys is mutable afterwards (doc `27` 阶段 2a). **`fp-5` opens a Team's
+* Leader the same way**: an optional `team_id` runs the `team/run` orchestration
+* (members, template, fences) but stops before the goal turn, so the client
+* speaks first; `agent_id` and `team_id` are mutually exclusive (阶段 2b).
+* **`fp-6` makes the model and the reasoning level selectable per call**:
+* `conversation/send` and `agent/run` each gain an optional `model` and
+* `reasoning_effort`. The scope is deliberately the **conversation** (send) and
+* the **run** (agent/run), not "just this turn": the Nomi runtime is built from
+* the persisted row, so a send-carried value is a sticky switch that takes
+* effect on that very turn (doc `29` §4). `ConversationView` also gains
+* `reasoning_effort`, because a setting that can be written by three methods but
+* read back by none is not a setting a client can honour (doc `29` §5.5).
+* **`fp-7` adds the `zip` marketplace source kind**: `market/add` accepts
+* `source_kind: "zip"`, one archive whose root *is* the market root. The
+* official bundles move to it because the old `url` form made a first fetch
+* mirror 14,714 files (611 MiB) for `experts` alone (doc `30`).
+* **`fp-8` adds expert definition export**: `agent/export` and `team/export`
+* return an {@link ExpertPack} — the persona, model hints, skill references and
+* (for a team) the roster with every member expanded. Nothing existing changes
+* shape, but the response carries the Agent Markdown body, which the catalog
+* faces deliberately never do; both methods are WebSocket-only, so the
+* documented route split becomes `48 / 73` (doc `32`).
+* **`fp-13` adds the market policy face** (doc `37`): `market/settings` reads the
+* host's effective sweep cadence, auto-upgrade kind whitelist and last-sweep
+* reading, and `market/settings-set` writes the named keys through to the host's
+* `config.toml`. The same change makes the background sweep able to upgrade
+* entries installed from an `auto_update` market (official sources only, and
+* never a `connector` or a component the user switched off by hand). Both
+* methods are mapped, so the documented route split becomes `55 / 80`.
+* **`fp-14` gives the expert pack its plugin-level assets** (doc `38`):
+* `import/assets` lists the `avatars/`, `bin/` and `scripts/` files of an
+* immutable snapshot (sorted, sha256-digested) and `import/asset` serves one of
+* them base64; `ExpertPack` gains an `assets` list and a declared `avatar` path
+* (`pack_format 2`), so an exported team can materialize a directory the
+* package's own scripts recognize as the plugin root. Both methods are
+* WebSocket-only, so the documented route split becomes `55 / 82`.
+*/
+const APP_SERVER_PROTOCOL_VERSION = "fp-14";
+/**
+* Format version of {@link ExpertPack}.
+*
+* **Independent of {@link APP_SERVER_PROTOCOL_VERSION}** on purpose: the
+* fingerprint versions *our* wire compatibility, this versions the **artifact
+* contract for third-party runtimes**. Gate on this one; the fingerprint is
+* about whether your client can talk to the host at all.
+*/
+const APP_SERVER_EXPERT_PACK_FORMAT = 2;
+//#endregion
+//#region src/errors.ts
+var AppServerError = class extends Error {
+	code;
+	requestId;
+	retryable;
+	details;
+	constructor(wire) {
+		super(wire.message);
+		this.name = "AppServerError";
+		this.code = wire.code;
+		this.requestId = wire.request_id;
+		this.retryable = wire.retryable;
+		this.details = wire.details ?? {};
+	}
+};
+var TransportError = class extends Error {
+	phase;
+	retryable;
+	cause;
+	constructor(phase, message, options) {
+		super(message);
+		this.name = "TransportError";
+		this.phase = phase;
+		this.retryable = options?.retryable ?? false;
+		this.cause = options?.cause;
+	}
+};
+var ProtocolError = class extends Error {
+	kind;
+	constructor(kind, message) {
+		super(message);
+		this.name = "ProtocolError";
+		this.kind = kind;
+	}
+};
+var RequestTimeoutError = class extends Error {
+	method;
+	timeoutMs;
+	constructor(method, timeoutMs) {
+		super(`app-server request timed out after ${timeoutMs}ms: ${method}`);
+		this.name = "RequestTimeoutError";
+		this.method = method;
+		this.timeoutMs = timeoutMs;
+	}
+};
+function isAppServerError(error) {
+	return error instanceof AppServerError;
+}
+function isRetryableTransportError(error) {
+	return error instanceof TransportError && error.retryable;
+}
+/**
+* Single human-readable rendering of a caught error.
+*
+* Every UI surface shares this one: a bare `Error` contributes only its
+* message, while a protocol error contributes its stable `code` plus the
+* server's retry hint. Components must not grow their own variants — a
+* second spelling means the two drift apart on the retry hint.
+*/
+function formatError(error) {
+	if (error instanceof AppServerError) return `${error.code}: ${error.message}`;
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+/** Whether the caught error is retryable — used by UI surfaces to append a
+*  localized "（可重试）" hint without baking wording into this lib. */
+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
+export { APP_SERVER_EXPERT_PACK_FORMAT, APP_SERVER_PROTOCOL_VERSION, AppServerError, ProtocolError, RequestTimeoutError, TransportError, booleanValue, contentToText, decodeConversationEvent, formatError, isAppServerError, isRecord, isRetryableError, isRetryableTransportError, numberValue, otherLocalizedLang, parseContextUsage, parseTurnUsage, pickEntryTags, pickEntryText, pickLocalized, pickLocalizedList, pickVariantList, pickVariantText, planData, stringValue, thinkingData, tipsData, toLocalizedLang, toolCallData };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flowy-agent-store/protocol",
+  "version": "0.1.0-beta.10",
+  "description": "Versioned App Server Protocol types and wire errors (no runtime, no DOM/Node deps)",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michael-Lfx/allo.git",
+    "directory": "web/packages/protocol"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts"
+}