@lanes-sh/link 0.4.1 → 0.5.0

package/src/providers/assets/provider.ts

@@ -0,0 +1,337 @@
+import { z } from 'zod';
+import {
+  attachmentRefSchema,
+  guessContentType,
+  receiptFor,
+  resolveAttachments,
+} from '#connectivity/mail';
+import { defineLocalProvider, keepKeys, type ProviderDefinition } from '#connectivity';
+import {
+  allAssets,
+  assertAssetName,
+  describeAsset,
+  digestOf,
+  findAsset,
+  humanBytes,
+  isTextual,
+} from './store.ts';
+
+/**
+ * `assets` — files the owner wants kept.
+ *
+ * **This exists because memory holds Markdown.** A PDF, an image, an export had
+ * nowhere to live except the owner's own filesystem — which a deployed endpoint
+ * cannot reach at all, so on any target but `local` the answer was that there
+ * was no answer. An asset is a file in the profile's own store, named, listed,
+ * and served from wherever that profile runs. ADR-051.
+ *
+ * **Bytes never pass through the model, in either direction.** A write names one
+ * of the five sources `#connectivity/mail` already resolves — a path on the
+ * endpoint's machine, an HTTPS URL, a staged handle, an attachment on a message,
+ * or inline base64 as the last resort — and the endpoint reads them itself. That
+ * is not a new rule: it is ADR-017's, reused rather than restated, which also
+ * buys the size ceiling, the refusal when two sources are named, and the
+ * SHA-256 receipt that makes "what exactly was stored" answerable.
+ *
+ * A read is the same rule the other way. `ResourceContents` carries text and
+ * nothing else (`#connectivity`'s `capability.ts`), so a text asset comes back
+ * as text and a binary one comes back *described* — name, type, size, digest.
+ * A 239 KB PDF is roughly 320,000 characters of base64, and handing that to a
+ * model is the cost the five sources exist to avoid; there is no reason to pay
+ * it on the way in that would not also apply on the way out.
+ *
+ * **Getting an asset into a mail is not done here**, and that is a boundary
+ * rather than a gap. A staged handle is scoped to `<provider>/<connection>`
+ * (`#dispatch`'s `stageAttachment`), so a handle minted under `assets/main` is
+ * deliberately unresolvable from `gmail/main` — bridging the two means crossing
+ * the isolation every provider relies on, and that belongs in dispatch if it
+ * belongs anywhere. `lanes link attach <file> --connection <provider>.<account>`
+ * already prints a handle the mail tools accept.
+ */
+
+const DEFAULT_LIMIT = 30;
+
+/**
+ * The ceiling on one stored asset.
+ *
+ * Not a vendor limit — there is no vendor. It bounds what a `url` source can
+ * pull into the endpoint's memory in one call, which is the only place an
+ * unbounded read could come from, and it is sized so an ordinary document,
+ * spreadsheet, or photograph goes through and a video does not.
+ */
+const MAX_ASSET_BYTES = 25 * 1024 * 1024;
+
+/** How much text a read will return before it describes the file instead. */
+const MAX_TEXT_BYTES = 256 * 1024;
+
+export const assetsProvider: ProviderDefinition = defineLocalProvider({
+  id: 'assets',
+  name: 'Assets',
+  version: '1.0.0',
+  description:
+    "Files the owner wants kept, addressed by filename. Storing one names a source — a path, a URL, a staged handle — and the endpoint reads the bytes; they are never encoded into a call. Writing is a separate capability from reading.",
+
+  configSchema: z.object({}),
+  connectionSchema: z.object({}),
+
+  bundles: [
+    {
+      name: 'read',
+      description: 'List and read stored files.',
+      oauth_scopes: [],
+      capabilities: ['file', 'list', 'get'],
+      default: true,
+    },
+    {
+      name: 'write',
+      description: 'Store and delete files.',
+      oauth_scopes: [],
+      capabilities: ['store', 'remove'],
+    },
+  ],
+
+  capabilities: [
+    {
+      kind: 'resource',
+      name: 'file',
+      title: 'Stored file',
+      description:
+        'One stored file, addressed by its name. Text comes back as text; anything else is described rather than encoded.',
+      uriTemplate: 'assets://file/{name}',
+      redact: keepKeys('uri'),
+
+      async list(context) {
+        return (await allAssets(context.storage)).map((asset) => ({
+          uri: `assets://file/${encodeURIComponent(asset.name)}`,
+          name: asset.name,
+        }));
+      },
+
+      async read(uri, params, context) {
+        const raw = params['name'];
+        if (!raw) throw new Error(`Malformed asset URI: ${uri}`);
+
+        const name = decodeURIComponent(raw);
+        const asset = await findAsset(context.storage, name);
+        if (asset === null) throw new Error(`No asset "${name}" on ${context.connection.key}`);
+
+        const bytes = await context.storage.get(name);
+        if (bytes === null) throw new Error(`No asset "${name}" on ${context.connection.key}`);
+
+        return textOrSummary(uri, name, asset.contentType, bytes);
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'list',
+      title: 'List stored files',
+      description:
+        'Every file kept in this profile, newest first, with its type and size. This is the whole index — an asset carries no description, so what a file is for belongs in memory.',
+      inputSchema: z.object({
+        query: z.string().optional().describe('Restrict to names containing this text'),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe(`Maximum results (default ${DEFAULT_LIMIT})`),
+      }),
+      // Nothing kept: a filename is the owner's own material, the same call
+      // `memory.search` makes about a query.
+      async handler({ query, limit }, context) {
+        const needle = query?.toLowerCase();
+        const all = await allAssets(context.storage);
+        const found = needle ? all.filter((a) => a.name.toLowerCase().includes(needle)) : all;
+        const shown = found.slice(0, limit ?? DEFAULT_LIMIT);
+
+        context.audit.annotate({ scanned: all.length, matched: found.length });
+
+        if (shown.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No ${needle ? 'matching ' : ''}assets on ${context.connection.key}.`,
+              },
+            ],
+          };
+        }
+
+        return {
+          content: [
+            ...shown.flatMap((asset) => [
+              {
+                type: 'resource_link' as const,
+                uri: `assets://file/${encodeURIComponent(asset.name)}`,
+                name: asset.name,
+              },
+              { type: 'text' as const, text: describeAsset(asset) },
+            ]),
+            ...(found.length > shown.length
+              ? [
+                  {
+                    type: 'text' as const,
+                    text: `… ${found.length - shown.length} more. Raise limit, or narrow with query.`,
+                  },
+                ]
+              : []),
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'get',
+      title: 'Read a stored file',
+      description:
+        'Return a text file\'s contents. A binary file is described instead — name, type, size, digest — because encoding it here is the cost this provider exists to avoid. The resource assets://file/{name} is the same content.',
+      inputSchema: z.object({ name: z.string().min(1).describe('The file name') }),
+      redact: keepKeys('name'),
+      async handler({ name }, context) {
+        const asset = await findAsset(context.storage, name);
+        const bytes = asset === null ? null : await context.storage.get(name);
+
+        if (asset === null || bytes === null) {
+          return {
+            content: [{ type: 'text', text: `No asset "${name}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        const { text } = textOrSummary('', name, asset.contentType, bytes);
+        return { content: [{ type: 'text', text }] };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'store',
+      title: 'Store a file',
+      description:
+        'Keep a file in this profile. Name exactly one source — path, url, handle, message_id, or data — and the endpoint reads the bytes itself; never base64 a file into this call when any other source will do. Storing under a name that exists replaces it.',
+      inputSchema: z.object({
+        source: attachmentRefSchema.describe(
+          'Where the bytes come from. Exactly one of path, url, handle, message_id, or data.',
+        ),
+        name: z
+          .string()
+          .optional()
+          .describe('What to call it. Taken from the source when omitted.'),
+      }),
+      // The name and the source shape are the record of what happened; the bytes
+      // are the content. `annotate` below adds the resolved facts, which is the
+      // half that makes a write log worth reading — see ADR-017.
+      redact: keepKeys('name'),
+      async handler({ source, name }, context) {
+        const [resolved] = await resolveAttachments([source], {
+          maxTotalBytes: MAX_ASSET_BYTES,
+          storage: context.storage,
+          signal: context.signal,
+        });
+
+        if (!resolved) throw new Error('source named no file.');
+
+        const assetName = name ?? resolved.filename;
+        assertAssetName(assetName);
+
+        // Renaming can improve the type. `resolveAttachments` guesses from the
+        // *source's* filename, so storing a URL that ended `/download` as
+        // `report.csv` arrives as octet-stream; the name the owner chose is the
+        // better evidence, but only where the source had none to offer.
+        const contentType =
+          name && resolved.contentType === 'application/octet-stream'
+            ? guessContentType(assetName)
+            : resolved.contentType;
+        const replaced = await context.storage.has(assetName);
+
+        await context.storage.put(assetName, resolved.bytes, { contentType });
+
+        // The resolved facts rather than the argument: `source` may literally be
+        // a file, so keeping it verbatim would put base64 in the log. This is
+        // the same annotation `gmail.send_message` records.
+        context.audit.annotate({ asset: assetName, replaced, ...receiptFor(resolved), origin: resolved.origin });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text:
+                `${replaced ? 'Replaced' : 'Stored'} "${assetName}" on ${context.connection.key} — ` +
+                `${contentType}, ${humanBytes(resolved.bytes.byteLength)}, sha256 ${resolved.sha256.slice(0, 12)}…`,
+            },
+            {
+              type: 'resource_link',
+              uri: `assets://file/${encodeURIComponent(assetName)}`,
+              name: assetName,
+            },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'remove',
+      title: 'Delete a stored file',
+      description: 'Remove a file and its bytes. There is no trash.',
+      inputSchema: z.object({ name: z.string().min(1).describe('The file name') }),
+      redact: keepKeys('name'),
+      async handler({ name }, context) {
+        assertAssetName(name);
+
+        const existed = await context.storage.has(name);
+        await context.storage.delete(name);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: existed
+                ? `Deleted "${name}" from ${context.connection.key}.`
+                : `No asset "${name}" on ${context.connection.key}.`,
+            },
+          ],
+          ...(existed ? {} : { isError: true }),
+        };
+      },
+    },
+  ],
+});
+
+/**
+ * Text if it can be, a description if it cannot.
+ *
+ * One function for both the tool and the resource, so the two cannot come to
+ * different conclusions about the same file — which is the failure that would
+ * make "read it as a resource instead" a workaround for a refusal.
+ */
+function textOrSummary(
+  uri: string,
+  name: string,
+  contentType: string,
+  bytes: Uint8Array,
+): { uri: string; mimeType: string; text: string } {
+  if (isTextual(contentType, bytes) && bytes.byteLength <= MAX_TEXT_BYTES) {
+    return { uri, mimeType: contentType, text: new TextDecoder().decode(bytes) };
+  }
+
+  const why =
+    bytes.byteLength > MAX_TEXT_BYTES
+      ? `larger than the ${humanBytes(MAX_TEXT_BYTES)} a read returns`
+      : 'not text';
+
+  return {
+    uri,
+    mimeType: 'text/plain',
+    text:
+      `${name} — ${contentType}, ${humanBytes(bytes.byteLength)}, sha256 ${digestOf(bytes)}.\n` +
+      `Its contents are ${why}, so they are not returned. ` +
+      'To attach it to something, ask the owner for a handle: ' +
+      'lanes link attach <file> --connection <provider>.<account>',
+  };
+}
+
+export default assetsProvider;

package/src/providers/assets/store.ts

@@ -0,0 +1,167 @@
+import { createHash } from 'node:crypto';
+import { guessContentType } from '#connectivity/mail';
+import type { BlobStore } from '#connectivity';
+
+/**
+ * How an asset is stored, and the only place that knows.
+ *
+ * **The key is the filename.** `invoice-2026-03.pdf` is stored at
+ * `assets/<connection>/invoice-2026-03.pdf`, and that is the whole of the
+ * layout — no id, no prefix, no sidecar, no index. `BlobStore.list()` already
+ * reports size and mtime, and the content type follows from the extension, so
+ * every fact a listing needs is either the key itself or something the store
+ * already had. Nothing is written twice and nothing can disagree.
+ *
+ * That is memory's design carried over rather than a new one: ADR-014 reversed
+ * an index-plus-body split for exactly this reason, and it applies harder here,
+ * because a sidecar holding an asset's name would be a second name for a file
+ * that already has one. What the owner sees under
+ * `~/.lanes-link/data/<profile>/assets/main/` is a directory of their files,
+ * with their names, openable by anything.
+ *
+ * The cost is that an asset carries no description, and that is deliberate:
+ * "the March invoice is in assets as invoice-2026-03.pdf" is a memory entry.
+ * Prose in a store with no way to search it would be worse than either.
+ */
+
+/**
+ * What may be a name, and why it is narrower than a filename.
+ *
+ * No path separator, so the namespace stays flat: `scopeBlobStore` would happily
+ * accept `a/b` and create a directory, and a listing that nests is one where
+ * `list()`'s single prefix scan stops describing what is there. No leading dot,
+ * because a dotfile is invisible in exactly the directory the owner is meant to
+ * be able to read. No control characters, which are not names.
+ *
+ * Spaces and unicode are allowed. Refusing them would reject the names files
+ * actually have, and the name is percent-encoded at the one boundary that needs
+ * it — a resource URI — rather than being restricted to survive it.
+ */
+const MAX_NAME = 200;
+const CONTROL = /[\x00-\x1F\x7F]/;
+
+/**
+ * Suffixes a blob adapter treats as its own bookkeeping.
+ *
+ * The filesystem adapter writes `<key>.meta` beside a blob whose content type its
+ * extension cannot express, `<key>.tmp` while a write is in flight, and skips
+ * both in `list()`. So an asset called `report.meta` would be stored, would
+ * never appear in a listing, and would read back only if you already knew the
+ * name — silent, and shaped like data loss. Memory never met this because every
+ * key it writes ends `.md`; an asset's key is whatever the file was called.
+ */
+const ADAPTER_SUFFIXES = ['.meta', '.tmp'];
+
+export function assertAssetName(name: string): void {
+  const why = nameProblem(name);
+  if (why) throw new Error(`Asset name ${JSON.stringify(name)} ${why}`);
+}
+
+function nameProblem(name: string): string | null {
+  if (name.length === 0) return 'must not be empty.';
+  if (name.length > MAX_NAME) return `must be at most ${MAX_NAME} characters.`;
+  if (name.includes('/') || name.includes('\\')) {
+    return 'must not contain a path separator — assets are a flat set of files, not a tree.';
+  }
+  if (name.startsWith('.')) return 'must not start with a dot.';
+  if (CONTROL.test(name)) return 'must not contain control characters.';
+
+  const reserved = ADAPTER_SUFFIXES.find((suffix) => name.endsWith(suffix));
+  if (reserved) {
+    return `must not end in "${reserved}" — a blob store keeps its own bookkeeping under that suffix and would hide the file.`;
+  }
+
+  return null;
+}
+
+/** Whether a listed key is an asset. Anything unnameable is skipped, not repaired. */
+export function nameFromKey(key: string): string | null {
+  return nameProblem(key) === null ? key : null;
+}
+
+export interface Asset {
+  readonly name: string;
+  readonly bytes: number;
+  readonly contentType: string;
+  readonly modifiedAt: string;
+}
+
+/**
+ * Every asset, newest first.
+ *
+ * One `list()` and no reads at all, which is the payoff for the key being the
+ * filename: memory has to open every entry to list it, and this does not.
+ */
+export async function allAssets(storage: BlobStore): Promise<Asset[]> {
+  return (await storage.list())
+    .flatMap((blob) => {
+      const name = nameFromKey(blob.key);
+      return name === null
+        ? []
+        : [
+            {
+              name,
+              bytes: blob.size,
+              contentType: blob.contentType ?? guessContentType(name),
+              modifiedAt: blob.modifiedAt.toISOString(),
+            },
+          ];
+    })
+    .sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt) || a.name.localeCompare(b.name));
+}
+
+export async function findAsset(storage: BlobStore, name: string): Promise<Asset | null> {
+  return (await allAssets(storage)).find((asset) => asset.name === name) ?? null;
+}
+
+export function digestOf(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * Whether these bytes can be handed to a model as text.
+ *
+ * Two questions, and both have to pass. The declared type has to be a text one
+ * — `text/*`, or a structured type that is text by construction — and the bytes
+ * have to contain no NUL, because a mislabelled binary is common and a content
+ * type is a claim rather than an observation. Failing either means the asset is
+ * described instead of returned, which is the honest answer: `ResourceContents`
+ * carries text and nothing else, and base64 into a conversation is the cost this
+ * whole mechanism exists to avoid.
+ */
+export function isTextual(contentType: string, bytes: Uint8Array): boolean {
+  const type = contentType.split(';')[0]!.trim().toLowerCase();
+
+  const declared =
+    type.startsWith('text/') ||
+    type.endsWith('+json') ||
+    type.endsWith('+xml') ||
+    ['application/json', 'application/xml', 'application/yaml', 'application/x-yaml'].includes(
+      type,
+    );
+
+  return declared && !bytes.includes(0);
+}
+
+/** `invoice.pdf  application/pdf  184 KB  2026-08-27` */
+export function describeAsset(asset: Asset): string {
+  return `${asset.name}  ${asset.contentType}  ${humanBytes(asset.bytes)}  ${asset.modifiedAt.slice(0, 10)}`;
+}
+
+export function humanBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** The pieces `lanes link assets` needs to reach the same bytes the provider does. */
+export const assetStorage = {
+  all: allAssets,
+  find: findAsset,
+  describe: describeAsset,
+  humanBytes,
+  digest: digestOf,
+  assertName: assertAssetName,
+  nameFromKey,
+  isTextual,
+};

package/src/providers/google/index.ts

@@ -7,5 +7,5 @@ export { driveMcp } from './drive-mcp/index.ts';
 export { gmail, GMAIL_SCOPES } from './gmail/index.ts';
 export { gmailImap } from './gmail-imap/index.ts';
 export { gmailMcp } from './gmail-mcp/index.ts';
+export { googleTasks } from './tasks/index.ts';
 export { sheets } from './sheets/index.ts';
-export { tasks } from './tasks/index.ts';

package/src/providers/google/tasks/index.ts

@@ -17,7 +17,7 @@ import { TASKS_REDACT } from './redact.ts';
  * What bounds it is what bounds the others. The token can delete a whole list;
  * the tool surface cannot, because `tasklists.delete` is not vendored — Tasks
  * has no trash, so destroying a list destroys every task in it. `lanes link
- * policy deny tasks.*` narrows it further.
+ * policy deny google_tasks.*` narrows it further.
  *
  * No `identity` block, and that is a decision rather than an omission. Nothing
  * reachable under `auth/tasks` returns an address: `tasklists.list` answers
@@ -32,8 +32,8 @@ import { TASKS_REDACT } from './redact.ts';
  */
 const TASKS_SCOPES = ['https://www.googleapis.com/auth/tasks'];
 
-export const tasks = defineProvider({
-  id: 'tasks',
+export const googleTasks = defineProvider({
+  id: 'google_tasks',
   name: 'Google Tasks',
   description:
     'Read and write task lists and tasks — create, edit, complete, reorder, and delete — via the Tasks REST API.',

package/src/providers/google/tasks/redact.ts

@@ -6,18 +6,28 @@
  * them. `due` and `status` are kept, because "marked the thing due Friday done"
  * is the shape of the change and neither argument says what the thing was.
  *
+ * **The keys carry Google's whole operationId**, `tasks.tasks.patch` rather than
+ * `tasks.patch`. `shortenName` strips the provider id from a discovered tool
+ * name, and this provider's id is `google_tasks` while the API namespaces its
+ * operations under `tasks` — so nothing is stripped and the capability is
+ * `google_tasks.tasks.patch`. `contacts` has read this way since it shipped: its
+ * id is `contacts` and the People API says `people.people.searchContacts`. The
+ * keys were the short form while the id was `tasks` and the prefix happened to
+ * match; renaming the provider for the built-in task list (ADR-051) ended the
+ * coincidence.
+ *
  * Two argument names are not what they look like, and a wrong key here fails
  * silently — the lookup misses, every value is withheld, and it reads exactly
  * like working redaction. The generator disambiguates a collision between a
  * path or query parameter and a body field by prefixing the location, so
- * `tasks.insert` takes `queryParent` (the query one) beside the body's
- * `parent`. `tasks.move` has no such collision and takes a plain `parent`.
+ * `tasks.tasks.insert` takes `queryParent` (the query one) beside the body's
+ * `parent`. `tasks.tasks.move` has no such collision and takes a plain `parent`.
  */
 export const TASKS_REDACT: Record<string, string[]> = {
-  'tasklists.list': ['maxResults'],
-  'tasklists.insert': [],
-  'tasklists.patch': ['tasklist'],
-  'tasks.list': [
+  'tasks.tasklists.list': ['maxResults'],
+  'tasks.tasklists.insert': [],
+  'tasks.tasklists.patch': ['tasklist'],
+  'tasks.tasks.list': [
     'tasklist',
     'showCompleted',
     'showDeleted',
@@ -26,9 +36,9 @@ export const TASKS_REDACT: Record<string, string[]> = {
     'dueMax',
     'maxResults',
   ],
-  'tasks.get': ['tasklist', 'task'],
-  'tasks.insert': ['tasklist', 'queryParent', 'previous', 'due', 'status'],
-  'tasks.patch': ['tasklist', 'task', 'due', 'status'],
-  'tasks.delete': ['tasklist', 'task'],
-  'tasks.move': ['tasklist', 'task', 'parent', 'previous'],
+  'tasks.tasks.get': ['tasklist', 'task'],
+  'tasks.tasks.insert': ['tasklist', 'queryParent', 'previous', 'due', 'status'],
+  'tasks.tasks.patch': ['tasklist', 'task', 'due', 'status'],
+  'tasks.tasks.delete': ['tasklist', 'task'],
+  'tasks.tasks.move': ['tasklist', 'task', 'parent', 'previous'],
 };

package/src/providers/index.ts

@@ -11,7 +11,7 @@ import { gmail } from './google/gmail/index.ts';
 import { gmailImap } from './google/gmail-imap/index.ts';
 import { gmailMcp } from './google/gmail-mcp/index.ts';
 import { sheets } from './google/sheets/index.ts';
-import { tasks } from './google/tasks/index.ts';
+import { googleTasks } from './google/tasks/index.ts';
 import { icloudCalendar } from './icloud/calendar/index.ts';
 import { icloudContacts } from './icloud/contacts/index.ts';
 import { icloudDrive } from './icloud/drive/index.ts';
@@ -63,7 +63,7 @@ export const PROVIDERS: readonly (ProviderManifest | ProviderDefinition)[] = [
   sheets,
   docs,
   calendar,
-  tasks,
+  googleTasks,
   contacts,
   gmailImap,
   gmailMcp,
@@ -97,8 +97,8 @@ export {
   gmail,
   gmailImap,
   gmailMcp,
+  googleTasks,
   sheets,
-  tasks,
 } from './google/index.ts';
 export { icloudCalendar, icloudContacts, icloudDrive, icloudMail } from './icloud/index.ts';
 export { bunq } from './bunq/index.ts';