@flowy-agent-store/protocol 0.1.0-beta.7 → 0.1.0-beta.9

package/dist/index.cjs

@@ -63,8 +63,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * 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`.
 */
-const APP_SERVER_PROTOCOL_VERSION = "fp-8";
+const APP_SERVER_PROTOCOL_VERSION = "fp-13";
 /**
 * Format version of {@link ExpertPack}.
 *

package/dist/index.d.cts

@@ -62,8 +62,15 @@
  * 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`.
  */
-export declare const APP_SERVER_PROTOCOL_VERSION = "fp-8";
+export declare const APP_SERVER_PROTOCOL_VERSION = "fp-13";
 export interface JsonRpcRequest {
   jsonrpc: "2.0";
   id: number | string;
@@ -883,6 +890,31 @@ export interface SkillDeleteResult {
   revealed_origin?: SkillOrigin | null;
 }
 export type ConnectorStatus = "installed" | "configured" | "authorization_required" | "authenticated" | "connected" | "degraded" | "error" | "reauthorization_required";
+/** `connector/register` — a connector the host never imported (doc `34` §6.5). */
+export interface ConnectorRegistration {
+  /** Its name on this host. Re-registering the same name updates it. */
+  name: string;
+  description?: string | null;
+  /**
+   * The template the host will store and later resolve — the same shape it keeps
+   * for a marketplace connector. Whatever `${secret:NAME}` its URL, headers or env
+   * name becomes the credential form; `values` carries the connector's own
+   * non-secret settings.
+   */
+  transport: ConnectorTransport;
+}
+/** The transport template, mirroring the host's own stored shape. */
+export type ConnectorTransport = {
+  type: "http" | "sse";
+  url: string;
+  headers?: Record<string, string>;
+  values?: Record<string, string>;
+} | {
+  type: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
 export interface ConnectorSummary {
   id: string;
   name: string;
@@ -897,6 +929,58 @@ export interface ConnectorSummary {
    * Absent for builtin hosts and for markets that ship no icon for the entry.
    */
   avatar_url?: string | null;
+  /**
+   * What the connector needs the user to fill in, when the host can describe it
+   * (doc `34` §6.1). Absent for a connector with no declaration and nothing to
+   * ask for.
+   *
+   * **Never carries a secret value**: `fields[].value` exists only for `plain`
+   * fields, which are the connector's own settings (`HOST`, `PORT`), and
+   * `missing` holds key names.
+   */
+  credential?: ConnectorCredential | null;
+}
+/** Both languages, already resolved by the host (doc `34` §5.2). */
+export interface LocalizedString {
+  zh: string;
+  en: string;
+}
+/** How a connector authenticates. */
+export type CredentialMode = "none" | "oauth" | "token";
+/** What the caller has to do about it. */
+export type CredentialStatus = "not_required" | "requires_input" | "configured" | "error";
+/** One row of the credential form. */
+export interface CredentialField {
+  key: string;
+  /** `secret` (the host's credential store) or `plain` (the connector's own value). */
+  kind: "secret" | "plain";
+  required: boolean;
+  label: LocalizedString;
+  placeholder: LocalizedString;
+  description: LocalizedString;
+  /** Only for `plain`: the value in effect. A secret's value never crosses the wire. */
+  value?: string | null;
+}
+/** The credential form and its state, as this caller sees them (doc `34` §6.1). */
+export interface ConnectorCredential {
+  connector_id: string;
+  mode: CredentialMode;
+  status: CredentialStatus;
+  /** Key names still missing for this caller — never values. */
+  missing: string[];
+  fields: CredentialField[];
+  /**
+   * Form-level text from the marketplace declaration (doc `34` §5.2).
+   *
+   * A `token-schema.json` declares its title, its description and its "where do I
+   * get a key" link **once, for the form** — the market ships no per-field links,
+   * and copying the form's onto every field reads as "how do I get a key" under
+   * `PORT`.
+   */
+  title?: LocalizedString | null;
+  description?: LocalizedString | null;
+  doc_url?: LocalizedString | null;
+  doc_label?: LocalizedString | null;
 }
 export interface ConnectorTool {
   name: string;
@@ -1218,6 +1302,73 @@ export interface StoreList {
    *  background (D-SDK-1 ①) — the catalog may be incomplete. */
   markets_pending?: boolean;
 }
+/**
+ * The host's effective market policy (doc `37` §3.2, `fp-13`).
+ *
+ * Two different questions, deliberately in one view: *when* the sweep runs
+ * (`auto_update_interval_hours`) and *what it may touch*
+ * (`entry_auto_update_kinds`). Both are read from the host's `config.toml` on
+ * every call — nothing here is an in-memory override.
+ */
+export interface MarketSettings {
+  /**
+   * Sweep cadence in hours. `null` = the background sweep is off.
+   *
+   * `0` is the wire spelling for "turn it off" on the way in
+   * ({@link MarketSettingsPatch}), and reads back as `null`, because the host's
+   * own `cadence()` already treats `0` as off rather than "every tick".
+   */
+  auto_update_interval_hours: number | null;
+  /**
+   * Entry kinds the sweep may auto-upgrade.
+   *
+   * Empty = the sweep only refreshes market indexes (the behaviour before doc
+   * `37`). The default is `["agent", "team", "skill"]`: `"connector"` is never
+   * implicit, because upgrading a connector reruns `upsert_server`, which marks
+   * the server **disabled** whenever its configuration changed — an unattended
+   * upgrade would silently disconnect a connector the user is using (`36` §3.4).
+   */
+  entry_auto_update_kinds: StoreItemKind[];
+  /**
+   * Whether this host actually runs a sweep at all.
+   *
+   * A host with no resolved `config.toml` path (the desktop host) reports
+   * `false` and never sweeps, so a client must not read "the cadence is set" as
+   * "updates will happen".
+   */
+  sweep_enabled: boolean;
+  /** The most recent sweep, or `null` before the first one. In-memory only. */
+  last_sweep: MarketSweepReport | null;
+}
+/**
+ * `market/settings-set` patch. An **absent** field means "leave it alone" — the
+ * two fields are independent, so a caller can change the cadence without
+ * restating the whitelist.
+ */
+export interface MarketSettingsPatch {
+  /** Absent = unchanged; `0` = off; `> 0` = hours between sweeps. */
+  auto_update_interval_hours?: number;
+  /** Absent = unchanged; `[]` = upgrade nothing (index refresh only). */
+  entry_auto_update_kinds?: StoreItemKind[];
+}
+/** One background sweep's reading (doc `37` §3.2, D8). */
+export interface MarketSweepReport {
+  /** Epoch ms when the sweep finished. */
+  at: number;
+  /** Markets whose index refresh succeeded this round. */
+  refreshed: number;
+  /** Entries actually upgraded. */
+  upgraded: number;
+  /** Entries that were candidates and failed. Never silently dropped. */
+  failed: MarketSweepFailure[];
+}
+/** One entry the sweep refused to upgrade, with the host's own reason. */
+export interface MarketSweepFailure {
+  /** `<marketplace_id>/<entry_name>` — the {@link StoreItem.id} spelling. */
+  id: string;
+  /** Server-authored prose (not an i18n key). */
+  error: string;
+}
 /** One model in the public catalog (`models/list`, REQ-PAR-05b). Provider
  *  credentials, base URLs and health internals never cross this projection. */
 export interface ModelSummary {
@@ -1238,7 +1389,8 @@ export interface StoreInstallResult {
   entry_name: string;
   snapshot_id: string;
   version: string;
-  /** true when the components were already registered (no-op install). */
+  /** true when the components were already registered (no-op install), or — for
+   *  an update — when the entry was already at the advertised version. */
   reused: boolean;
   installed_count: number;
   warnings: string[];
@@ -1247,6 +1399,15 @@ export interface StoreInstallResult {
    *  store install is as branchable as a direct `install/run`. Absent on a host
    *  that predates the field. */
   outcomes?: InstallOutcome[];
+  /** Version the entry was installed at before this call (`store/update-entry`
+   *  only; absent means "this was an install"). */
+  previous_version?: string | null;
+  /** The snapshot that was replaced. Same rule as `previous_version`. */
+  previous_snapshot_id?: string | null;
+  /** Components of the replaced snapshot whose runtime artifacts were actually
+   *  released. `0` on an install, on a no-op update, and when a failed update
+   *  left the previous installation in place. */
+  released_count?: number;
 }
 export interface LocalizedText {
   en?: string | null;
@@ -1423,6 +1584,16 @@ export interface ExpertPack {
   description?: string | null;
   persona: ExpertPersona;
   model: ExpertModel;
+  /**
+   * The Definition's Skills, **by reference** — fetch the bytes with
+   * `skills.files()` / `skills.readFile()`.
+   *
+   * Two sources, deliberately not merged on the wire: an **agent** pack's list is
+   * that expert's own declaration, while a **team** pack's list is what the team's
+   * own package installed, and each member keeps its own declaration in
+   * `team.members[].skills`. An empty list means the package ships no skills, not
+   * that you should go look at the members. `materializePack` unions both.
+   */
   skills: ExpertSkillRef[];
   connectors: ExpertConnectorRef[];
   tool_policy: ExpertToolPolicy;

package/dist/index.d.mts

@@ -62,8 +62,15 @@
  * 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`.
  */
-export declare const APP_SERVER_PROTOCOL_VERSION = "fp-8";
+export declare const APP_SERVER_PROTOCOL_VERSION = "fp-13";
 export interface JsonRpcRequest {
   jsonrpc: "2.0";
   id: number | string;
@@ -883,6 +890,31 @@ export interface SkillDeleteResult {
   revealed_origin?: SkillOrigin | null;
 }
 export type ConnectorStatus = "installed" | "configured" | "authorization_required" | "authenticated" | "connected" | "degraded" | "error" | "reauthorization_required";
+/** `connector/register` — a connector the host never imported (doc `34` §6.5). */
+export interface ConnectorRegistration {
+  /** Its name on this host. Re-registering the same name updates it. */
+  name: string;
+  description?: string | null;
+  /**
+   * The template the host will store and later resolve — the same shape it keeps
+   * for a marketplace connector. Whatever `${secret:NAME}` its URL, headers or env
+   * name becomes the credential form; `values` carries the connector's own
+   * non-secret settings.
+   */
+  transport: ConnectorTransport;
+}
+/** The transport template, mirroring the host's own stored shape. */
+export type ConnectorTransport = {
+  type: "http" | "sse";
+  url: string;
+  headers?: Record<string, string>;
+  values?: Record<string, string>;
+} | {
+  type: "stdio";
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
 export interface ConnectorSummary {
   id: string;
   name: string;
@@ -897,6 +929,58 @@ export interface ConnectorSummary {
    * Absent for builtin hosts and for markets that ship no icon for the entry.
    */
   avatar_url?: string | null;
+  /**
+   * What the connector needs the user to fill in, when the host can describe it
+   * (doc `34` §6.1). Absent for a connector with no declaration and nothing to
+   * ask for.
+   *
+   * **Never carries a secret value**: `fields[].value` exists only for `plain`
+   * fields, which are the connector's own settings (`HOST`, `PORT`), and
+   * `missing` holds key names.
+   */
+  credential?: ConnectorCredential | null;
+}
+/** Both languages, already resolved by the host (doc `34` §5.2). */
+export interface LocalizedString {
+  zh: string;
+  en: string;
+}
+/** How a connector authenticates. */
+export type CredentialMode = "none" | "oauth" | "token";
+/** What the caller has to do about it. */
+export type CredentialStatus = "not_required" | "requires_input" | "configured" | "error";
+/** One row of the credential form. */
+export interface CredentialField {
+  key: string;
+  /** `secret` (the host's credential store) or `plain` (the connector's own value). */
+  kind: "secret" | "plain";
+  required: boolean;
+  label: LocalizedString;
+  placeholder: LocalizedString;
+  description: LocalizedString;
+  /** Only for `plain`: the value in effect. A secret's value never crosses the wire. */
+  value?: string | null;
+}
+/** The credential form and its state, as this caller sees them (doc `34` §6.1). */
+export interface ConnectorCredential {
+  connector_id: string;
+  mode: CredentialMode;
+  status: CredentialStatus;
+  /** Key names still missing for this caller — never values. */
+  missing: string[];
+  fields: CredentialField[];
+  /**
+   * Form-level text from the marketplace declaration (doc `34` §5.2).
+   *
+   * A `token-schema.json` declares its title, its description and its "where do I
+   * get a key" link **once, for the form** — the market ships no per-field links,
+   * and copying the form's onto every field reads as "how do I get a key" under
+   * `PORT`.
+   */
+  title?: LocalizedString | null;
+  description?: LocalizedString | null;
+  doc_url?: LocalizedString | null;
+  doc_label?: LocalizedString | null;
 }
 export interface ConnectorTool {
   name: string;
@@ -1218,6 +1302,73 @@ export interface StoreList {
    *  background (D-SDK-1 ①) — the catalog may be incomplete. */
   markets_pending?: boolean;
 }
+/**
+ * The host's effective market policy (doc `37` §3.2, `fp-13`).
+ *
+ * Two different questions, deliberately in one view: *when* the sweep runs
+ * (`auto_update_interval_hours`) and *what it may touch*
+ * (`entry_auto_update_kinds`). Both are read from the host's `config.toml` on
+ * every call — nothing here is an in-memory override.
+ */
+export interface MarketSettings {
+  /**
+   * Sweep cadence in hours. `null` = the background sweep is off.
+   *
+   * `0` is the wire spelling for "turn it off" on the way in
+   * ({@link MarketSettingsPatch}), and reads back as `null`, because the host's
+   * own `cadence()` already treats `0` as off rather than "every tick".
+   */
+  auto_update_interval_hours: number | null;
+  /**
+   * Entry kinds the sweep may auto-upgrade.
+   *
+   * Empty = the sweep only refreshes market indexes (the behaviour before doc
+   * `37`). The default is `["agent", "team", "skill"]`: `"connector"` is never
+   * implicit, because upgrading a connector reruns `upsert_server`, which marks
+   * the server **disabled** whenever its configuration changed — an unattended
+   * upgrade would silently disconnect a connector the user is using (`36` §3.4).
+   */
+  entry_auto_update_kinds: StoreItemKind[];
+  /**
+   * Whether this host actually runs a sweep at all.
+   *
+   * A host with no resolved `config.toml` path (the desktop host) reports
+   * `false` and never sweeps, so a client must not read "the cadence is set" as
+   * "updates will happen".
+   */
+  sweep_enabled: boolean;
+  /** The most recent sweep, or `null` before the first one. In-memory only. */
+  last_sweep: MarketSweepReport | null;
+}
+/**
+ * `market/settings-set` patch. An **absent** field means "leave it alone" — the
+ * two fields are independent, so a caller can change the cadence without
+ * restating the whitelist.
+ */
+export interface MarketSettingsPatch {
+  /** Absent = unchanged; `0` = off; `> 0` = hours between sweeps. */
+  auto_update_interval_hours?: number;
+  /** Absent = unchanged; `[]` = upgrade nothing (index refresh only). */
+  entry_auto_update_kinds?: StoreItemKind[];
+}
+/** One background sweep's reading (doc `37` §3.2, D8). */
+export interface MarketSweepReport {
+  /** Epoch ms when the sweep finished. */
+  at: number;
+  /** Markets whose index refresh succeeded this round. */
+  refreshed: number;
+  /** Entries actually upgraded. */
+  upgraded: number;
+  /** Entries that were candidates and failed. Never silently dropped. */
+  failed: MarketSweepFailure[];
+}
+/** One entry the sweep refused to upgrade, with the host's own reason. */
+export interface MarketSweepFailure {
+  /** `<marketplace_id>/<entry_name>` — the {@link StoreItem.id} spelling. */
+  id: string;
+  /** Server-authored prose (not an i18n key). */
+  error: string;
+}
 /** One model in the public catalog (`models/list`, REQ-PAR-05b). Provider
  *  credentials, base URLs and health internals never cross this projection. */
 export interface ModelSummary {
@@ -1238,7 +1389,8 @@ export interface StoreInstallResult {
   entry_name: string;
   snapshot_id: string;
   version: string;
-  /** true when the components were already registered (no-op install). */
+  /** true when the components were already registered (no-op install), or — for
+   *  an update — when the entry was already at the advertised version. */
   reused: boolean;
   installed_count: number;
   warnings: string[];
@@ -1247,6 +1399,15 @@ export interface StoreInstallResult {
    *  store install is as branchable as a direct `install/run`. Absent on a host
    *  that predates the field. */
   outcomes?: InstallOutcome[];
+  /** Version the entry was installed at before this call (`store/update-entry`
+   *  only; absent means "this was an install"). */
+  previous_version?: string | null;
+  /** The snapshot that was replaced. Same rule as `previous_version`. */
+  previous_snapshot_id?: string | null;
+  /** Components of the replaced snapshot whose runtime artifacts were actually
+   *  released. `0` on an install, on a no-op update, and when a failed update
+   *  left the previous installation in place. */
+  released_count?: number;
 }
 export interface LocalizedText {
   en?: string | null;
@@ -1423,6 +1584,16 @@ export interface ExpertPack {
   description?: string | null;
   persona: ExpertPersona;
   model: ExpertModel;
+  /**
+   * The Definition's Skills, **by reference** — fetch the bytes with
+   * `skills.files()` / `skills.readFile()`.
+   *
+   * Two sources, deliberately not merged on the wire: an **agent** pack's list is
+   * that expert's own declaration, while a **team** pack's list is what the team's
+   * own package installed, and each member keeps its own declaration in
+   * `team.members[].skills`. An empty list means the package ships no skills, not
+   * that you should go look at the members. `materializePack` unions both.
+   */
   skills: ExpertSkillRef[];
   connectors: ExpertConnectorRef[];
   tool_policy: ExpertToolPolicy;

package/dist/index.mjs

@@ -62,8 +62,15 @@
 * 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`.
 */
-const APP_SERVER_PROTOCOL_VERSION = "fp-8";
+const APP_SERVER_PROTOCOL_VERSION = "fp-13";
 /**
 * Format version of {@link ExpertPack}.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowy-agent-store/protocol",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.9",
   "description": "Versioned App Server Protocol types and wire errors (no runtime, no DOM/Node deps)",
   "type": "module",
   "license": "Apache-2.0",