@lanes-sh/link 0.8.0 → 0.9.1

package/src/providers/tasks/provider.ts

@@ -57,7 +57,7 @@ function matches(task: Task, needle: string): boolean {
 }
 
 export const tasksProvider: ProviderDefinition = defineLocalProvider({
-  id: 'tasks',
+  id: 'lanes_tasks',
   name: 'Tasks',
   version: '1.0.0',
   description:
@@ -92,13 +92,13 @@ export const tasksProvider: ProviderDefinition = defineLocalProvider({
       name: 'task',
       title: 'Task',
       description: 'One task, addressed by its id.',
-      uriTemplate: 'tasks://task/{id}',
+      uriTemplate: 'lanes-tasks://task/{id}',
       mimeType: 'text/markdown',
       redact: keepKeys('uri'),
 
       async list(context) {
         return (await allTasks(context.storage)).map((task) => ({
-          uri: `tasks://task/${encodeURIComponent(task.id)}`,
+          uri: `lanes-tasks://task/${encodeURIComponent(task.id)}`,
           name: task.title,
         }));
       },
@@ -170,7 +170,7 @@ export const tasksProvider: ProviderDefinition = defineLocalProvider({
             ...shown.flatMap((task) => [
               {
                 type: 'resource_link' as const,
-                uri: `tasks://task/${encodeURIComponent(task.id)}`,
+                uri: `lanes-tasks://task/${encodeURIComponent(task.id)}`,
                 name: task.title,
               },
               { type: 'text' as const, text: `${task.id}  ${line(task)}` },
@@ -193,7 +193,7 @@ export const tasksProvider: ProviderDefinition = defineLocalProvider({
       name: 'get',
       title: 'Read a task',
       description:
-        'Return one task by id, notes included. The resource tasks://task/{id} is the same content; this exists for clients that do not read resources.',
+        'Return one task by id, notes included. The resource lanes-tasks://task/{id} is the same content; this exists for clients that do not read resources.',
       inputSchema: z.object({ id: z.string().min(1).describe('Task id') }),
       redact: keepKeys('id'),
       async handler({ id }, context) {
@@ -261,7 +261,7 @@ export const tasksProvider: ProviderDefinition = defineLocalProvider({
               type: 'text',
               text: `${existing ? 'Replaced' : 'Added'} task "${taskId}" on ${context.connection.key}.`,
             },
-            { type: 'resource_link', uri: `tasks://task/${taskId}`, name: title },
+            { type: 'resource_link', uri: `lanes-tasks://task/${taskId}`, name: title },
           ],
         };
       },

package/src/providers/vault/provider.ts

@@ -92,7 +92,7 @@ export function createVaultProvider(options: VaultProviderOptions): ProviderDefi
   }));
 
   return defineLocalProvider({
-    id: 'vault',
+    id: 'lanes_vault',
     name: 'Vault',
     version: '1.0.0',
     description:

package/src/registry/registry.ts

@@ -78,7 +78,7 @@ export class ProviderRegistry {
 
     if (!this.#allowReserved && RESERVED_PROVIDER_IDS.includes(manifest.id)) {
       throw new Error(
-        `Provider id "${manifest.id}" is reserved for the owner layer (memory, skills, vault) and cannot be claimed.`,
+        `Provider id "${manifest.id}" is reserved for the owner layer (the lanes_ surfaces) and cannot be claimed.`,
       );
     }
 

package/src/server/endpoint.ts

@@ -176,6 +176,10 @@ function profileRuntimes(runtimes: ReadonlyMap<string, Runtime>): Map<string, Pr
       name,
       {
         config: runtime.config,
+        // For the `connection` argument's description: an id says nothing about
+        // which account it is, and the caller choosing between two of a vendor
+        // has only that description to go on.
+        connections: runtime.connections,
         registry: runtime.registry,
         dispatcher: runtime.dispatcher,
         policy: toPolicyDocument(runtime.config),

package/src/server/harness.ts

@@ -75,7 +75,7 @@ export function configFor(profile: string, port: number, policy: string): Config
     `  - connection: example.${id}\n${rules.replace(/^ {4}(allow|deny):/gm, '    $1:')}`;
 
   return parseConfig(`
-contract: 3
+contract: 4
 instance:
   profile: ${profile}
   port: ${port}

package/src/server/mcp/instructions.ts

@@ -102,12 +102,12 @@ quote it back, summarise it, or write it anywhere.`;
  * Asked to connect a second mailbox, a client with no setup surface and no
  * skill answered that it could not and then invented the procedure — edit the
  * profile YAML, run "the auth command" — neither of which is a thing. It had
- * no way to know `setup_overview` answers exactly that, so the instruction has
+ * no way to know `lanes_setup_overview` answers exactly that, so the instruction has
  * to arrive here: this is the only channel that reaches a client which has
  * merely been pointed at the URL.
  */
 const SETUP = `**What is set up is answerable.** Before saying something cannot be reached, or
-that an account must be added, call \`setup_overview\` — then \`setup_provider\`
+that an account must be added, call \`lanes_setup_overview\` — then \`lanes_setup_provider\`
 for the exact command. Running it is the owner's to do; inventing it is not.`;
 
 /**
@@ -117,14 +117,14 @@ for the exact command. Running it is the owner's to do; inventing it is not.`;
  * declaration would put a per-profile list into a string with a fixed ceiling —
  * so the workspace with the most identities to keep straight is exactly the one
  * whose list would be summarised away first. A pointer costs the same for one
- * profile as for twenty, and `identity_list` has room to say when each applies,
+ * profile as for twenty, and `lanes_identity_list` has room to say when each applies,
  * which is the half that actually prevents the mistake.
  *
  * Conditional like the rest: a profile that declares nothing has no `identity`
  * connection, so the capability is unreachable and this paragraph is unspent.
  */
 const IDENTITY = `**Identity is declared, not inferred.** Where a name, address or handle of the
-owner's is needed, call \`identity_list\`: a profile may hold several, each with a
+owner's is needed, call \`lanes_identity_list\`: a profile may hold several, each with a
 note on when it applies.`;
 
 /**
@@ -136,7 +136,7 @@ note on when it applies.`;
  * message sent to the wrong Jan has left.
  *
  * It carries two rules rather than one, because dropping the refusal made the
- * second necessary. `entities_find` returns every match and sets no error, so a
+ * second necessary. `lanes_entities_find` returns every match and sets no error, so a
  * client is not stopped by anything: nothing but this sentence stands between
  * "two candidates" and an agent using the first. The count and the wording of
  * the tool result say it too, and this says it before the first call rather
@@ -166,7 +166,7 @@ which is meant, not take the first.`;
  * form and this one arrives only once the owner has declared themselves.
  */
 const IDENTITY_AND_ENTITIES = `**Who someone is, is declared rather than inferred.** For the owner's own name,
-address or handle, call \`identity_list\`. For anyone else — a person, a company,
+address or handle, call \`lanes_identity_list\`. For anyone else — a person, a company,
 a project — call \`entities_find\`, which returns every match and never chooses:
 more than one means ask which is meant, not take the first.`;
 
@@ -201,14 +201,14 @@ not land, do not redo what already succeeded, and offer to retry.`;
 
 /** Which paragraph each owner-layer provider brings, when it is reachable alone. */
 const OWNER_HABITS: Record<string, string> = {
-  memory: MEMORY,
-  tasks: TASKS,
-  assets: ASSETS,
-  skills: SKILLS,
-  vault: VAULT,
-  setup: SETUP,
-  identity: IDENTITY,
-  entities: ENTITIES,
+  lanes_memory: MEMORY,
+  lanes_tasks: TASKS,
+  lanes_assets: ASSETS,
+  lanes_skills: SKILLS,
+  lanes_vault: VAULT,
+  lanes_setup: SETUP,
+  lanes_identity: IDENTITY,
+  lanes_entities: ENTITIES,
 };
 
 /**
@@ -228,14 +228,14 @@ const OWNER_HABITS: Record<string, string> = {
  */
 function habitsFor(reachable: readonly string[]): string[] {
   const present = new Set(reachable);
-  const stores = present.has('memory') && present.has('tasks');
-  const people = present.has('identity') && present.has('entities');
+  const stores = present.has('lanes_memory') && present.has('lanes_tasks');
+  const people = present.has('lanes_identity') && present.has('lanes_entities');
 
   return reachable.flatMap((id) => {
-    if (stores && id === 'memory') return [MEMORY_AND_TASKS];
-    if (stores && id === 'tasks') return [];
-    if (people && id === 'identity') return [IDENTITY_AND_ENTITIES];
-    if (people && id === 'entities') return [];
+    if (stores && id === 'lanes_memory') return [MEMORY_AND_TASKS];
+    if (stores && id === 'lanes_tasks') return [];
+    if (people && id === 'lanes_identity') return [IDENTITY_AND_ENTITIES];
+    if (people && id === 'lanes_entities') return [];
     return OWNER_HABITS[id] ? [OWNER_HABITS[id]!] : [];
   });
 }
@@ -270,7 +270,7 @@ function habitsFor(reachable: readonly string[]): string[] {
  * the wrong address has already sent the message; the mistake happens at the
  * instant of the send, before a skill would have been loaded, and the client
  * most in need of the rule is again the one holding no skills directory. The
- * paragraph also carries a rule nothing else can enforce: `entities_find` sets
+ * paragraph also carries a rule nothing else can enforce: `lanes_entities_find` sets
  * no error on an ambiguous result, so between "two candidates" and an agent
  * using the first there is only prose.
  *

package/src/server/mcp/routing.ts

@@ -16,8 +16,8 @@ import type { MergedCapability, ProfileRuntime } from './visibility.ts';
  * They have to go somewhere that works for *any* template, not just one that
  * happens to spell `{key}`, so they are inserted as the first two path segments
  * directly after the authority: `example://note/{key}` becomes
- * `example://note/personal/a/{key}`, and `memory://entry/{id}` becomes
- * `memory://entry/personal/owner/{id}`.
+ * `example://note/personal/a/{key}`, and `lanes-memory://entry/{id}` becomes
+ * `lanes-memory://entry/personal/owner/{id}`.
  *
  * The previous form substituted the literal token `{key}`, which meant any
  * provider naming its variable anything else — every provider except `example` —
@@ -53,7 +53,7 @@ function originOf(uri: string): string {
 /**
  * Route the `resource_link`s a tool hands back.
  *
- * A provider names its own resources — `memory://entry/deploy_window` — because
+ * A provider names its own resources — `lanes-memory://entry/deploy_window` — because
  * it does not know, and must not learn, which profile or connection it is
  * serving. Core does. Without this, `memory.search` returns addresses that look
  * like resources and cannot be read, which is worse than returning none.

package/src/server/mcp/tools.ts

@@ -6,7 +6,12 @@ import { clientLabelFrom } from './client-info.ts';
 import { toolNameFor } from './naming.ts';
 import { resourceLinkRouter } from './routing.ts';
 import { sanitizeSchema } from './schema.ts';
-import { describeWithConnections, type BuildServerOptions, type MergedCapability } from './visibility.ts';
+import {
+  accountsByProfile,
+  describeWithConnections,
+  type BuildServerOptions,
+  type MergedCapability,
+} from './visibility.ts';
 
 /**
  * Tools — the capability kind everything else is measured against.
@@ -51,7 +56,11 @@ export function registerDiscoveredTool(
     toolNameFor(id),
     {
       ...(discovered.title ? { title: discovered.title } : {}),
-      description: describeWithConnections(discovered.description, entry.reachable),
+      description: describeWithConnections(
+        discovered.description,
+        entry.reachable,
+        accountsByProfile(options),
+      ),
       // Spread the upstream schema rather than rebuilding it from properties
       // and required alone. Vendors put `$defs` beside those and `$ref` into
       // them — Linear's attachment tools do — and a rebuild drops the
@@ -87,7 +96,11 @@ export function registerLocalTool(
     toolNameFor(id),
     {
       ...(capability.title ? { title: capability.title } : {}),
-      description: describeWithConnections(capability.description, entry.reachable),
+      description: describeWithConnections(
+        capability.description,
+        entry.reachable,
+        accountsByProfile(options),
+      ),
       inputSchema: {
         ...shape,
         // Injected by core, never declared by a provider — ADR-001. Both enums

package/src/server/mcp/visibility.ts

@@ -1,6 +1,6 @@
 import { isTool } from '#connectivity';
 import type { Principal } from '#auth';
-import type { Config } from '#profile';
+import type { Config, SelectedConnection } from '#profile';
 import type { ProviderRegistry } from '#registry';
 import type { Dispatcher } from '#dispatch';
 import type { PolicyDocument, ProfilePolicy } from '#policy';
@@ -24,6 +24,15 @@ import { mayReach } from '#auth';
 /** Everything one profile contributes to the endpoint. */
 export interface ProfileRuntime {
   readonly config: Config;
+  /**
+   * The accounts this profile selects, for the `connection` argument's
+   * description — the id alone cannot say which mailbox it is.
+   *
+   * Optional because a registry built to read manifests has no selection, the
+   * same reason `refreshSkills` is: a harness that omits it gets bare ids, which
+   * is what this listed for everybody before.
+   */
+  readonly connections?: readonly SelectedConnection[];
   readonly registry: ProviderRegistry;
   readonly dispatcher: Dispatcher;
   readonly policy: ProfilePolicy;
@@ -166,13 +175,56 @@ export function visibleToolCount(options: BuildServerOptions): number {
  * Grouped rather than flattened because the two arguments are not independent:
  * `profile: personal` with a connection belonging to `work` is refused, and a
  * flat list would read as though any pairing were valid.
+ *
+ * **The account, not just the id.** This listed bare ids, and the id is the
+ * only thing a model has to choose on — so two accounts of one vendor were
+ * `ada_lovelace` and `ada_lovelace2` and nothing said which mailbox either was.
+ * `idFromAccount` takes only the local part, so that is what two addresses at
+ * different domains actually produce. Picking the wrong one sends mail as the
+ * wrong person, which is the same class of failure ADR-056 rules out for
+ * entities: ordering is not selection, and a caller that cannot tell two
+ * candidates apart must be given what tells them apart.
+ *
+ * The enum stays bare ids, because the id is what the caller passes.
  */
 export function describeWithConnections(
   description: string,
   reachable: ReadonlyMap<string, readonly string[]>,
+  accounts: ReadonlyMap<string, ReadonlyMap<string, string>> = new Map(),
 ): string {
-  const lines = [...reachable].map(
-    ([profile, connections]) => `  ${profile}: ${connections.join(', ')}`,
-  );
+  const lines = [...reachable].flatMap(([profile, connections]) => {
+    const known = accounts.get(profile);
+    return [
+      `  ${profile}:`,
+      ...connections.map((id) => `    ${id}${known?.get(id) === undefined ? '' : ` — ${known.get(id)!}`}`),
+    ];
+  });
   return `${description}\n\nAvailable connections, by profile:\n${lines.join('\n')}`;
 }
+
+/**
+ * How each profile's connections should read to a caller choosing between them.
+ *
+ * `account` always, `label` where the operator set one — the two fields that
+ * exist because the id cannot carry meaning and must not pretend to.
+ */
+export function accountsByProfile(
+  options: BuildServerOptions,
+): Map<string, Map<string, string>> {
+  const accounts = new Map<string, Map<string, string>>();
+
+  for (const [name, runtime] of options.profiles) {
+    const rows = new Map<string, string>();
+    for (const { connection } of runtime.connections ?? []) {
+      rows.set(
+        connection.id,
+        connection.label === undefined
+          ? connection.account
+          : `${connection.account} (${connection.label})`,
+      );
+    }
+    accounts.set(name, rows);
+  }
+
+  return accounts;
+}

package/src/stores/blobs/conformance.ts

@@ -177,6 +177,25 @@ export function describeBlobStoreContract(
       });
     });
 
+    test('allows a name that merely begins with dots', async () => {
+      await use(async (store) => {
+        // Not a traversal — an ordinary name that happens to start with two
+        // dots, which a provider will hand over verbatim because it is a
+        // caller's to choose. One adapter refused these and the rest stored
+        // them, so the same workspace behaved differently depending on which
+        // target it was opened against. That is the divergence this whole
+        // suite exists to catch, and it caught nothing until there was a case
+        // for it.
+        // Distinct names, because a filesystem cannot hold `x` as a file and
+        // `x/y` beneath it at once — a real difference between an object store
+        // and a directory tree, and not the one under test here.
+        for (const key of ['..config', '...rc', '..nested/inner.txt']) {
+          await store.put(key, bytes(key));
+          expect(text(await store.get(key))).toBe(key);
+        }
+      });
+    });
+
     test('allows a traversal that stays inside, normalised', async () => {
       await use(async (store) => {
         // Weaker than `scopeBlobStore`'s rule on purpose: the namespace

package/src/stores/state/index.ts

@@ -26,6 +26,11 @@
 import type { BlobStore } from '../blobs/index.ts';
 import { keyFromEntry, namespacePrefix, objectKey } from './keys.ts';
 
+// Re-exported because the contract-3 migration has to address objects this
+// module wrote, and deriving `connections%2Ev1/gmail%2Emain.json` by hand at the
+// call site is the second spelling of an encoding that must not have two.
+export { decodeSegment, encodeSegment, objectKey } from './keys.ts';
+
 export type ConnectionStatus =
   | 'active'
   /** Declared, but its credential is missing or rejected. Does not block startup. */
@@ -94,17 +99,78 @@ export interface RuntimeState {
  * contain. The same rule keeps `audit.log` and `state.kv` out of reach in
  * `#profile`'s layout.
  */
-const CONNECTIONS = 'connections.v1';
+export const CONNECTIONS_NAMESPACE = 'connections.v1';
 const CURSORS = 'cursors.v1';
 
+/**
+ * The discovery cache, and what the endpoint's own OAuth server remembers.
+ *
+ * Both carry a `.v1` for the reason `connections.v1` and `cursors.v1` do, and
+ * here it is doing more than versioning. A provider's own keys are namespaced
+ * `<provider>/<connection>` in this same store, a provider id is
+ * `[a-z][a-z0-9_]*`, and only `custom` is refused by grammar — so while these
+ * were spelled `discovery` and `oauth/clients`, a manifest with id `discovery`
+ * or `oauth` landed inside them. That was a collision when everything shared
+ * one store; with the workspace/profile split below it would be a silent
+ * cross-profile leak, because these two route to the workspace. A dotted name
+ * is one no provider can reach.
+ */
+export const DISCOVERY_NAMESPACE = 'discovery.v1';
+export const OAUTH_NAMESPACE = 'oauth.v1';
+
+/**
+ * Whether a namespace belongs to the workspace rather than to one profile.
+ *
+ * Connection records and the discovery cache are facts about an account or a
+ * provider — a `connect` run once must read as connected from every profile —
+ * and the OAuth server is the endpoint's, not a profile's. Everything else is
+ * this profile's use of an account: its cursors, and each provider's own keys.
+ *
+ * Every name here carries a dot, so the list cannot be entered by a provider.
+ */
+export function isWorkspaceNamespace(namespace: string): boolean {
+  return (
+    namespace === CONNECTIONS_NAMESPACE ||
+    namespace === DISCOVERY_NAMESPACE ||
+    namespace === OAUTH_NAMESPACE ||
+    namespace.startsWith(`${OAUTH_NAMESPACE}/`)
+  );
+}
+
+/**
+ * Runtime state over two stores: the workspace's, and one profile's.
+ *
+ * `kv` routes on the namespace rather than being two stores the caller picks
+ * between, because the callers are providers and they do not know which of
+ * their keys are shared — nor should they. `isWorkspaceNamespace` is the whole
+ * rule, and it is closed: a namespace it does not name is the profile's.
+ *
+ * Both are required, with no default that falls back to one. A default would
+ * mean forgetting the second argument shares every profile's cursors and
+ * provider keys silently — which is the failure this split exists to remove.
+ * Passing the same store twice is still how a test that is not exercising the
+ * split says so, and it says it out loud.
+ */
 export function createRuntimeState(
   blobs: BlobStore,
+  profileBlobs: BlobStore,
   now: () => Date = () => new Date(),
 ): RuntimeState {
-  const kv = createKeyValue(blobs);
+  const workspaceKv = createKeyValue(blobs);
+  const profileKv = createKeyValue(profileBlobs);
+  const forNamespace = (namespace: string): KeyValueStore =>
+    isWorkspaceNamespace(namespace) ? workspaceKv : profileKv;
+
+  const kv: KeyValueStore = {
+    get: (namespace, key) => forNamespace(namespace).get(namespace, key),
+    set: (namespace, key, value) => forNamespace(namespace).set(namespace, key, value),
+    delete: (namespace, key) => forNamespace(namespace).delete(namespace, key),
+    keys: (namespace) => forNamespace(namespace).keys(namespace),
+    clearNamespace: (namespace) => forNamespace(namespace).clearNamespace(namespace),
+  };
 
   const readConnection = async (provider: string, id: string): Promise<ConnectionRecord | null> =>
-    decodeConnection(await kv.get(CONNECTIONS, connectionKey(provider, id)));
+    decodeConnection(await workspaceKv.get(CONNECTIONS_NAMESPACE, connectionKey(provider, id)));
 
   const connections: ConnectionRepository = {
     async upsert(record) {
@@ -116,7 +182,7 @@ export function createRuntimeState(
         createdAt: existing?.createdAt ?? now(),
         updatedAt: now(),
       };
-      await kv.set(CONNECTIONS, connectionKey(record.provider, record.id), encodeConnection(stored));
+      await workspaceKv.set(CONNECTIONS_NAMESPACE, connectionKey(record.provider, record.id), encodeConnection(stored));
       return stored;
     },
 
@@ -124,8 +190,8 @@ export function createRuntimeState(
 
     async list() {
       const records: ConnectionRecord[] = [];
-      for (const key of await kv.keys(CONNECTIONS)) {
-        const record = decodeConnection(await kv.get(CONNECTIONS, key));
+      for (const key of await workspaceKv.keys(CONNECTIONS_NAMESPACE)) {
+        const record = decodeConnection(await workspaceKv.get(CONNECTIONS_NAMESPACE, key));
         if (record) records.push(record);
       }
       return records.sort(
@@ -136,8 +202,8 @@ export function createRuntimeState(
     async setStatus(provider, id, status) {
       const existing = await readConnection(provider, id);
       if (!existing) return;
-      await kv.set(
-        CONNECTIONS,
+      await workspaceKv.set(
+        CONNECTIONS_NAMESPACE,
         connectionKey(provider, id),
         encodeConnection({ ...existing, status, updatedAt: now() }),
       );
@@ -145,8 +211,8 @@ export function createRuntimeState(
   };
 
   const cursors: CursorRepository = {
-    get: (namespace) => kv.get(CURSORS, namespace),
-    set: (namespace, cursor) => kv.set(CURSORS, namespace, cursor),
+    get: (namespace) => profileKv.get(CURSORS, namespace),
+    set: (namespace, cursor) => profileKv.set(CURSORS, namespace, cursor),
   };
 
   return { connections, kv, cursors };

package/src/stores/state/testing.ts

@@ -15,7 +15,11 @@ import { createMemoryBlobStore } from '../blobs/testing.ts';
 import { createRuntimeState, type RuntimeState } from './index.ts';
 
 export function createMemoryState(now: () => Date = () => new Date()): RuntimeState {
-  return createRuntimeState(createMemoryBlobStore(), now);
+  // The same store twice: this harness is for callers that are not exercising
+  // the workspace/profile split, and saying so explicitly is the point of
+  // `createRuntimeState` having no default.
+  const blobs = createMemoryBlobStore();
+  return createRuntimeState(blobs, blobs, now);
 }
 
 /** An in-memory credential store, for the same reason. */