@holokai/harbor-sdk 0.3.0

package/README.md

@@ -0,0 +1,72 @@
+# @holokai/harbor-sdk
+
+The harbor extension to [MCP Apps](https://github.com/modelcontextprotocol/ext-apps): what a hosted
+view can ask harbor for beyond the MCP Apps spec, spelled once.
+
+Two entry points:
+
+- `@holokai/harbor-sdk/contract` — the public wire. Zero imports. Method names, params and result
+  types, a JSON Schema per method's params, the event map, the grant map, and the shape harbor
+  advertises under `hostCapabilities.experimental['ai.holokai/harbor']`. Harbor's own gate imports
+  this module for validation, so the SDK's types cannot drift from what the gate enforces.
+- `@holokai/harbor-sdk` — `connectHarbor(app)`: a thin layer OVER the ext-apps `App` instance
+  (never a second JSON-RPC client on the same channel). Returns `null` in any host that is not
+  harbor, so the same app runs unchanged in Claude, ChatGPT, VS Code or Goose as a plain MCP App.
+
+```ts
+import {App} from '@modelcontextprotocol/ext-apps';
+import {connectHarbor} from '@holokai/harbor-sdk';
+
+const app = new App({name: 'my-app', version: '1.0.0'});
+await app.connect();
+const harbor = connectHarbor(app);
+if (harbor) {
+    const {workflows} = await harbor.workflows.list({limit: 20});
+    const off = harbor.events.on('run.changed', ({workflow}) => console.log(workflow.status));
+}
+```
+
+Opening a file: `harbor.files.open({name, tool, arguments})` asks harbor to open a file the app
+identifies. Harbor calls `tool` on the app's own server; the tool answers a `CallToolResult` whose
+content holds exactly one `{type: 'resource', resource: {uri, mimeType?, blob}}` carrying the bytes
+base64. Harbor keeps a read-only copy named `name` and opens it in its own editor; the answer is
+`{name}`. Needs the `files.open` grant.
+
+Opening a link: `harbor.browser.open({url})` asks harbor to open a URL in the person's own browser.
+A view's frame is sandboxed without `allow-popups`, so a link of its own goes nowhere; this is the
+way out. **https only** — harbor parses the URL in its main process and refuses every other scheme
+with `-32602`, so `http:`, `file:`, `javascript:` and an application's own scheme are all dead
+regardless of what the page checks. The answer is `{url}` as harbor parsed it. Needs the
+`browser.open` grant.
+
+Saying what the page is showing: `reportView(app, {state, names, text})` sends one WHOLE snapshot of
+the view on the spec's own `ui/update-model-context`, and `savedView(app)` answers what harbor saved
+for this page last time. Neither goes through `connectHarbor`: `reportView` works under any MCP Apps
+host, and `savedView` answers `null` under every host but harbor. Call both after `app.connect()`.
+
+- **The advertisement is the disclosure.** Harbor answers `ui/initialize` with
+  `hostCapabilities.updateModelContext` naming the modalities it takes, and `reportView` sends only
+  those. A host that advertises no `structuredContent` is sent the text block and neither harbor
+  key, so a pane width and a subject line never enter a foreign host's context; a host that
+  advertises nothing is sent nothing at all.
+- **`view.state`** admits the structured view — `{place, item, filter, query, panes}`, harbor's key
+  under `structuredContent`. Harbor remembers it and hands it back; it goes nowhere else.
+- **`view.content`** admits what the page says in its own words (the `content` blocks) and the two
+  names it offers for what it has open (`{item, place}`, its own key under `structuredContent`).
+  Harbor holds these only while the view is mounted.
+- **Refused:** a `content` block that is not text — harbor advertises no other modality, so an
+  image, audio, a resource or a resource link is a `-32602` rather than a dropped block. So is a
+  structured half that is present but malformed: an unknown field, a string over 256 characters, a
+  `panes` bag over 8 entries, a pane name that is not a short identifier, or a pane width that is
+  not a finite number. **Not refused, simply not kept:** a half that is absent or ungranted, a key
+  belonging to another extension, a name over 120 characters or empty once its control characters
+  are gone, and text over the result budget — one unusable half never costs the report the other.
+- **The saved view arrives on the `ui/initialize` ANSWER**, under harbor's key in `hostContext`, so
+  a page reads it before its first frame. Harbor never pushes it again.
+
+What harbor does with each half, and why the two never cross, is `docs/design/hosted-apps.md`,
+section 9.
+
+Versioning: the extension object carries `version`; methods are additive within a major. Events are
+invalidation signals: a subscription's `seq` increments per delivered event, and a gap means "re-read
+a snapshot" — there is no replay.

package/dist/chunks/chunk-G4KJ2OCU.js

@@ -0,0 +1,319 @@
+import {createRequire as __harborCreateRequire} from 'node:module'; const require = __harborCreateRequire(import.meta.url);
+
+// src/contract.ts
+var HARBOR_EXTENSION_ID = "ai.holokai/harbor";
+var HARBOR_PAGE_READER = { tool: "read_page", reads: "page" };
+var HARBOR_EXTENSION_VERSION = "0.2";
+var MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
+var HARBOR_METHODS = {
+  workflowsList: "harbor/workflows/list",
+  workflowsSubmit: "harbor/workflows/submit",
+  workflowsGet: "harbor/workflows/get",
+  capabilitiesList: "harbor/capabilities/list",
+  eventsSubscribe: "harbor/events/subscribe",
+  eventsUnsubscribe: "harbor/events/unsubscribe",
+  filesOpen: "harbor/files/open",
+  filesAdd: "harbor/files/add",
+  filesLink: "harbor/files/link",
+  browserOpen: "harbor/browser/open",
+  barSet: "harbor/bar/set",
+  viewsOpen: "harbor/views/open",
+  viewStatus: "harbor/view/status"
+};
+var HARBOR_EVENT_NOTIFICATION = "harbor/notifications/event";
+var HARBOR_BAR_NOTIFICATION = "harbor/notifications/bar";
+var WORKFLOWS_LIST_LIMIT = { min: 1, max: 50, default: 20 };
+var WORKFLOW_TASKS_MAX = 50;
+var BAR_LIMITS = {
+  placeholderChars: 60,
+  labelChars: 60,
+  valueChars: 500,
+  nameChars: 80,
+  items: 8,
+  itemLabelChars: 60,
+  itemIdChars: 40
+};
+var VIEW_STATUSES = ["idle", "running", "waiting", "completed", "failed"];
+var HARBOR_VIEW_STATE_LIMITS = {
+  /** Longest a `place`, `item`, `filter` or `query` may be. */
+  valueChars: 256,
+  /** Most entries `panes` may carry. */
+  paneEntries: 8,
+  /** Longest a pane name may be. */
+  paneNameChars: 32
+};
+var PANE_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+var HARBOR_VIEW_STATE_STRING_KEYS = ["place", "item", "filter", "query"];
+function validateViewState(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, message: "the view state must be an object" };
+  }
+  const record = value;
+  const state = {};
+  for (const key of Object.keys(record)) {
+    const known = key === "panes" || HARBOR_VIEW_STATE_STRING_KEYS.includes(key);
+    if (!known) return { ok: false, message: `field '${key}' is not part of the view state` };
+  }
+  for (const key of HARBOR_VIEW_STATE_STRING_KEYS) {
+    const field = record[key];
+    if (field === void 0) continue;
+    if (typeof field !== "string") return { ok: false, message: `field '${key}' must be a string` };
+    if (field.length > HARBOR_VIEW_STATE_LIMITS.valueChars) {
+      return { ok: false, message: `field '${key}' is longer than ${HARBOR_VIEW_STATE_LIMITS.valueChars} chars` };
+    }
+    state[key] = field;
+  }
+  const panes = record["panes"];
+  if (panes !== void 0) {
+    if (typeof panes !== "object" || panes === null || Array.isArray(panes)) {
+      return { ok: false, message: "panes must be an object" };
+    }
+    const entries = Object.entries(panes);
+    if (entries.length > HARBOR_VIEW_STATE_LIMITS.paneEntries) {
+      return { ok: false, message: `panes takes at most ${HARBOR_VIEW_STATE_LIMITS.paneEntries} entries` };
+    }
+    const kept = {};
+    for (const [name, width] of entries) {
+      if (name.length > HARBOR_VIEW_STATE_LIMITS.paneNameChars || !PANE_NAME_PATTERN.test(name)) {
+        return { ok: false, message: "a pane name must be a short identifier" };
+      }
+      if (typeof width !== "number" || !Number.isFinite(width)) {
+        return { ok: false, message: "a pane width must be a finite number" };
+      }
+      kept[name] = width;
+    }
+    state.panes = kept;
+  }
+  return { ok: true, value: state };
+}
+var HARBOR_VIEW_NAMES_ID = "ai.holokai/harbor/names";
+var HARBOR_VIEW_NAME_LIMITS = {
+  /** Longest an `item`, `place` or step name may be; a longer one is not kept. */
+  nameChars: 120,
+  /** Most steps a trail may hold; past it, the first step and the innermost ones are kept. */
+  trailSteps: 12,
+  /** Longest a step's id may be; a step with a longer one, or one holding a control character, is not kept. */
+  stepIdChars: 256
+};
+var VIEW_NAME_KEYS = ["item", "place"];
+var VIEW_NAMES_FIELDS = [...VIEW_NAME_KEYS, "trail"];
+var CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+function validateViewNames(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, message: "the view names must be an object" };
+  }
+  const record = value;
+  const names = {};
+  for (const key of Object.keys(record)) {
+    if (!VIEW_NAMES_FIELDS.includes(key)) {
+      return { ok: false, message: `field '${key}' is not part of the view names` };
+    }
+  }
+  for (const key of VIEW_NAME_KEYS) {
+    const field = record[key];
+    if (field === void 0) continue;
+    if (typeof field !== "string") return { ok: false, message: `field '${key}' must be a string` };
+    const clean = cleanName(field);
+    if (clean !== null) names[key] = clean;
+  }
+  const trail = record["trail"];
+  if (trail !== void 0) {
+    if (!Array.isArray(trail)) return { ok: false, message: `field 'trail' must be an array` };
+    const steps = [];
+    const cap = HARBOR_VIEW_NAME_LIMITS.trailSteps;
+    const kept = trail.length <= cap ? trail : [trail[0], ...trail.slice(trail.length - (cap - 1))];
+    for (const step of kept) {
+      if (typeof step !== "object" || step === null || Array.isArray(step)) {
+        return { ok: false, message: `a trail step must be an object` };
+      }
+      const { id, name } = step;
+      if (typeof id !== "string" || typeof name !== "string") {
+        return { ok: false, message: `a trail step must have a string 'id' and 'name'` };
+      }
+      const cleanStepName = cleanName(name);
+      if (id.length === 0 || id.length > HARBOR_VIEW_NAME_LIMITS.stepIdChars || id.replace(CONTROL_CHARS, "") !== id || cleanStepName === null) {
+        continue;
+      }
+      steps.push({ id, name: cleanStepName });
+    }
+    if (steps.length > 0) names.trail = steps;
+  }
+  return { ok: true, value: names };
+}
+function cleanName(field) {
+  const clean = field.replace(CONTROL_CHARS, " ").trim();
+  return clean.length === 0 || clean.length > HARBOR_VIEW_NAME_LIMITS.nameChars ? null : clean;
+}
+var UPDATE_MODEL_CONTEXT_PARAMS_SCHEMA = {
+  type: "object",
+  properties: {
+    content: { type: "array", description: "Context blocks for the model; harbor takes text blocks only." },
+    structuredContent: { type: "object", description: "Machine-readable context, keyed by extension id." },
+    _meta: { type: "object" }
+  }
+};
+var HARBOR_EVENT_NAMES = [
+  "harbor.heartbeat",
+  "run.changed",
+  "workflow.task",
+  "workflow.changed",
+  "server.notification"
+];
+var HARBOR_METHOD_PARAMS_SCHEMA = {
+  "harbor/workflows/list": {
+    type: "object",
+    properties: { limit: { type: "integer", description: "How many, newest first. 1..50, default 20." } }
+  },
+  "harbor/workflows/submit": {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "A human label for the run; the server assigns the id." },
+      description: { type: "string" },
+      tasks: { type: "array", description: "The DAG, as WorkflowTaskSpec rows; validated in depth by harbor." }
+    },
+    required: ["name", "tasks"]
+  },
+  "harbor/workflows/get": {
+    type: "object",
+    properties: { workflowId: { type: "string" } },
+    required: ["workflowId"]
+  },
+  // No params: an empty properties map means any key is refused.
+  "harbor/capabilities/list": { type: "object", properties: {} },
+  "harbor/events/subscribe": {
+    type: "object",
+    properties: { events: { type: "array", description: "Event names to receive; each must be a known name." } },
+    required: ["events"]
+  },
+  "harbor/events/unsubscribe": {
+    type: "object",
+    properties: { subscriptionId: { type: "string" } },
+    required: ["subscriptionId"]
+  },
+  "harbor/files/open": {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "The file name to open the copy under; a bare name, no folders." },
+      tool: { type: "string", description: "The app's own tool that returns the file's bytes." },
+      arguments: { type: "object", description: "Arguments for that tool." }
+    },
+    required: ["name", "tool"]
+  },
+  "harbor/files/add": {
+    type: "object",
+    properties: {
+      name: { type: "string", description: "The file name to save it under; a bare name, no folders." },
+      tool: { type: "string", description: "The app's own tool that returns the file's bytes." },
+      arguments: { type: "object", description: "Arguments for that tool." }
+    },
+    required: ["name", "tool"]
+  },
+  "harbor/files/link": {
+    type: "object",
+    properties: {
+      id: { type: "string", description: "A folder or file id this app's own tools gave." },
+      url: { type: "string", description: "The folder's address on its provider's own site." }
+    },
+    required: ["id"]
+  },
+  "harbor/browser/open": {
+    type: "object",
+    // `_meta` is the one key MCP allows on ANY request's params (a progress
+    // token rides it), and the validator refuses what a schema does not
+    // name — so a client that attaches one would be told its field is not
+    // allowed. `tools/call` names it for the same reason.
+    properties: {
+      url: { type: "string", description: "An https URL to open in the person\u2019s own browser." },
+      _meta: { type: "object" }
+    },
+    required: ["url"]
+  },
+  "harbor/bar/set": {
+    type: "object",
+    properties: {
+      search: {
+        type: "object",
+        description: "The search field, or null for none; its shape and caps are checked by harbor."
+      },
+      account: {
+        type: "object",
+        description: "The account menu, or null for none; its shape and caps are checked by harbor."
+      },
+      _meta: { type: "object" }
+    }
+  },
+  "harbor/views/open": {
+    type: "object",
+    properties: {
+      title: { type: "string", description: "What the new window is called until its page names what it shows." },
+      view: { type: "object", description: "The saved view the new page boots with; a HarborViewState." },
+      _meta: { type: "object" }
+    },
+    required: ["title", "view"]
+  },
+  "harbor/view/status": {
+    type: "object",
+    properties: {
+      status: {
+        type: "string",
+        enum: VIEW_STATUSES,
+        description: "What the page's tray button shows: idle, running, waiting, completed or failed."
+      },
+      _meta: { type: "object" }
+    },
+    required: ["status"]
+  }
+};
+var HARBOR_GRANT_OF = {
+  "harbor/workflows/list": "workflows.read",
+  "harbor/workflows/submit": "workflows.submit",
+  "harbor/workflows/get": "workflows.submit",
+  "harbor/capabilities/list": "capabilities.read",
+  "harbor/events/subscribe": "by-params",
+  "harbor/events/unsubscribe": "by-params",
+  "harbor/files/open": "files.open",
+  "harbor/files/add": "files.add",
+  "harbor/files/link": "files.add",
+  "harbor/browser/open": "browser.open",
+  "harbor/bar/set": "bar.set",
+  "harbor/views/open": "views.open",
+  "harbor/view/status": "view.state",
+  "harbor.heartbeat": "events.diagnostic",
+  "run.changed": "events.runs",
+  "workflow.task": "workflows.submit",
+  "workflow.changed": "workflows.submit",
+  "server.notification": "server.tools"
+};
+var STANDARD_METHOD_GRANT_OF = {
+  "tools/call": "server.tools",
+  "resources/list": "server.resources",
+  "resources/read": "server.resources",
+  "ui/update-model-context": ["view.state", "view.content"]
+};
+var WORKFLOW_TITLE_GRANT = "workflows.content";
+
+export {
+  HARBOR_EXTENSION_ID,
+  HARBOR_PAGE_READER,
+  HARBOR_EXTENSION_VERSION,
+  MCP_APPS_PROTOCOL_VERSION,
+  HARBOR_METHODS,
+  HARBOR_EVENT_NOTIFICATION,
+  HARBOR_BAR_NOTIFICATION,
+  WORKFLOWS_LIST_LIMIT,
+  WORKFLOW_TASKS_MAX,
+  BAR_LIMITS,
+  VIEW_STATUSES,
+  HARBOR_VIEW_STATE_LIMITS,
+  HARBOR_VIEW_STATE_STRING_KEYS,
+  validateViewState,
+  HARBOR_VIEW_NAMES_ID,
+  HARBOR_VIEW_NAME_LIMITS,
+  validateViewNames,
+  UPDATE_MODEL_CONTEXT_PARAMS_SCHEMA,
+  HARBOR_EVENT_NAMES,
+  HARBOR_METHOD_PARAMS_SCHEMA,
+  HARBOR_GRANT_OF,
+  STANDARD_METHOD_GRANT_OF,
+  WORKFLOW_TITLE_GRANT
+};