@lanes-sh/link 0.4.1 → 0.5.0

package/src/providers/owner.ts

@@ -1,38 +1,58 @@
 /**
- * The owner layer — memory, skills, vault, setup, identity.
+ * The owner layer — memory, tasks, assets, skills, vault, setup, identity.
  *
- * Three providers that hold no third-party account: no OAuth, no vendor API, no
+ * Seven providers that hold no third-party account: no OAuth, no vendor API, no
  * rate limit anyone else imposes. They are ordinary `defineLocalProvider`
- * registrations, configured by the same `lanes link connect <provider>`, scoped by the
- * same profiles, and gated by the same policy evaluation as everything else —
- * which was the claim `docs/detailed/init.md` made and called the real test of the
- * architecture.
+ * registrations, scoped by the same profiles and gated by the same policy
+ * evaluation as everything else — which was the claim `docs/detailed/init.md`
+ * made and called the real test of the architecture. Since ADR-050 they are also
+ * the ones a fresh profile arrives with already granted, because what they reach
+ * is the owner's own material and there is no account behind them to protect.
  *
- * They live in `./memory/`, `./skills/` and `./vault/`, beside `google/` and
- * `icloud/`, because that claim is only true if they are providers in the
- * layout as well as in the prose. This file is the one thing they share: a
- * barrel, because each is *constructed* with a store rather than declared as
- * data, so `#profile`'s registry builder needs all three together.
+ * Each lives in its own folder beside `google/` and `icloud/`, because that
+ * claim is only true if they are providers in the layout as well as in the
+ * prose. This file is the one thing they share: a barrel, because several are
+ * *constructed* with a store rather than declared as data, so the registry
+ * builder needs them together.
  *
- * `setup` joined them later and is the same shape: it holds no account either,
- * and it describes the other three rather than reaching anything. It is
- * read-only by construction — see ADR-019 for why describing setup is not one
+ * `memory`, `tasks` and `assets` are the three that hold what the owner keeps,
+ * and they divide by what a thing *is* rather than by size: memory is what is
+ * true, tasks is what is to be done, assets is a file. That split is the whole
+ * of ADR-051, and the routing rule an agent needs is stated in
+ * `#server/mcp`'s instructions and in the bundled skill.
+ *
+ * `setup` is the same shape and holds no account either, but it describes the
+ * others rather than holding anything of the owner's. It is read-only by
+ * construction — see ADR-019 for why describing setup is not one
  * of ADR-007's control-plane exclusions.
  *
- * `identity` is the fifth and holds no account either. It says who the owner is
+ * `identity` holds no account either. It says who the owner is
  * — the names and addresses to write as them — and is read-only for the reason
  * `setup` is: what it reports is configuration, and configuration is changed in
  * the CLI. It is a provider of its own rather than a section of `setup` so that
  * naming the owner and describing what is connected are two policy decisions
  * instead of one.
  *
- * The ids `memory`, `skills`, `vault`, `setup`, and `identity` are reserved (`RESERVED_PROVIDER_IDS`)
- * and still refused by default — the registry has to be built with
- * `allowReserved` to hold them, so a third-party provider cannot claim a
- * namespace whose policy rules would then mean something else.
+ * All seven ids are reserved (`RESERVED_PROVIDER_IDS`) and still refused by
+ * default — the registry has to be built with `allowReserved` to hold them, so a
+ * third-party provider cannot claim a namespace whose policy rules would then
+ * mean something else. `tasks` cost something to reserve: Google Tasks held that
+ * id and was renamed `google_tasks`, because the plain noun belongs to the
+ * owner's own list and a manifest already registered under it would have thrown
+ * on the second registration rather than shadowing anything.
  */
 
 export { memoryProvider, memoryStorage, assertEntryId, type MemoryEntry } from './memory/provider.ts';
+export { tasksProvider } from './tasks/provider.ts';
+export {
+  ACTIVE_STATUSES,
+  TASK_STATUSES,
+  taskStorage,
+  type Task,
+  type TaskStatus,
+} from './tasks/store.ts';
+export { assetsProvider } from './assets/provider.ts';
+export { assetStorage, type Asset } from './assets/store.ts';
 export { createSkillsProvider, type SkillsProviderOptions } from './skills/provider.ts';
 export { createVaultProvider, type VaultProviderOptions } from './vault/provider.ts';
 export { createSetupProvider, type SetupProviderOptions } from './setup/provider.ts';

package/src/providers/setup/plan.ts

@@ -1,5 +1,5 @@
 import type { ProviderManifest } from '#connectivity';
-import { hasOwnClientPath, setupRequirements, type SetupRequirement } from '#connectivity';
+import { hasOwnClientPath, RESERVED_PROVIDER_IDS, setupRequirements, type SetupRequirement } from '#connectivity';
 
 /**
  * What connecting a provider involves, assembled from its manifest.
@@ -19,6 +19,21 @@ export interface ProviderPlan {
   readonly id: string;
   readonly name: string;
   readonly description: string;
+  /**
+   * This provider is part of what a profile *is*, not an account it holds.
+   *
+   * The owner layer — `memory`, `skills`, `vault`, `setup`, `identity` — keyed off
+   * `RESERVED_PROVIDER_IDS`, which is the same list the registry uses to stop a
+   * third-party manifest claiming one of those ids.
+   *
+   * Reported because it is the fact a surface needs and cannot derive.
+   * `multiAccount` is the nearest thing and it is not it: that is a credential
+   * test, and `icloud_drive` is `auth: none` without being owner-layer at all. A
+   * client wanting to group these, or to withhold a disconnect that would leave a
+   * dangling policy grant, was left hardcoding the list — which then goes stale
+   * the next time one is added here. This travels with the release instead.
+   */
+  readonly reserved: boolean;
   /** Connection keys of this provider already configured, e.g. `gmail.main`. */
   readonly connected: readonly string[];
   /**
@@ -122,6 +137,7 @@ export function planFor(
     id: manifest.id,
     name: manifest.name,
     description: manifest.description,
+    reserved: RESERVED_PROVIDER_IDS.includes(manifest.id),
     connected,
     multiAccount: manifest.auth.kind !== 'none',
     browser: manifest.auth.kind === 'oauth',

package/src/providers/tasks/provider.ts

@@ -0,0 +1,370 @@
+import { z } from 'zod';
+import { defineLocalProvider, keepKeys, type ProviderDefinition } from '#connectivity';
+import {
+  ACTIVE_STATUSES,
+  TASK_STATUSES,
+  allTasks,
+  assertTaskId,
+  readTask,
+  slugify,
+  taskKey,
+  writeTask,
+  type Task,
+  type TaskStatus,
+} from './store.ts';
+
+/**
+ * `tasks` — what the owner has to do.
+ *
+ * **This exists because memory was being used for it.** "Remember to chase the
+ * invoice" was landing in `memory.write`, and memory has no way to express that
+ * something is finished: an entry is a fact, facts do not close, and nothing
+ * ever removed it. A task carries a status, which is the whole difference, and
+ * the routing rule is stated where an agent reads it — the paragraph in
+ * `#server/mcp`'s instructions and the bundled skill both say that a thing to
+ * *do* goes here and a thing that is merely *true* goes in memory. ADR-051.
+ *
+ * Everything else is memory's design, deliberately unchanged: one Markdown file
+ * per task in the `BlobStore` core scoped to `tasks/<connection>`, reading and
+ * writing as separate capabilities, no index. The format lives in `./store.ts`.
+ *
+ * **Reading and writing are separate**, for the reason ADR-012 §2 gives for
+ * memory: text an agent authors is stored once and re-served to every later
+ * session, including to a different agent. A task list is a smaller version of
+ * that risk rather than a different one — an injected "task" is an instruction
+ * with a due date — so the split is the same and so is the one-line narrowing,
+ * `deny: [tasks.add, tasks.update, tasks.remove]`.
+ */
+
+const DEFAULT_LIMIT = 20;
+
+const statusSchema = z.enum(TASK_STATUSES);
+
+/** `in_progress · chase the invoice  (due 2026-09-01) [billing]` */
+function line(task: Task): string {
+  const tags = task.tags.length > 0 ? ` [${task.tags.join(', ')}]` : '';
+  const due = task.due ? `  (due ${task.due})` : '';
+  return `${task.status} · ${task.title}${due}${tags}`;
+}
+
+/** Whether a task matches a free-text query, over the parts a person would search. */
+function matches(task: Task, needle: string): boolean {
+  return (
+    task.title.toLowerCase().includes(needle) ||
+    task.body.toLowerCase().includes(needle) ||
+    task.tags.some((tag) => tag.toLowerCase().includes(needle))
+  );
+}
+
+export const tasksProvider: ProviderDefinition = defineLocalProvider({
+  id: 'tasks',
+  name: 'Tasks',
+  version: '1.0.0',
+  description:
+    "What the owner has to do. A task carries a status, which is why this is not memory: use it for anything to be done, and memory for what is merely true. Writing is a separate capability from reading.",
+
+  configSchema: z.object({}),
+  connectionSchema: z.object({}),
+
+  bundles: [
+    {
+      name: 'read',
+      description: 'List and read tasks.',
+      oauth_scopes: [],
+      capabilities: ['task', 'list', 'get'],
+      default: true,
+    },
+    {
+      name: 'write',
+      description: 'Add tasks, change their status, and delete them.',
+      oauth_scopes: [],
+      capabilities: ['add', 'update', 'remove'],
+    },
+  ],
+
+  capabilities: [
+    /**
+     * Retrieval by address — a resource, not a tool, on ADR-006's rule: the
+     * answer is a function of the URI alone. The same case memory's `entry` is.
+     */
+    {
+      kind: 'resource',
+      name: 'task',
+      title: 'Task',
+      description: 'One task, addressed by its id.',
+      uriTemplate: '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)}`,
+          name: task.title,
+        }));
+      },
+
+      async read(uri, params, context) {
+        const raw = params['id'];
+        if (!raw) throw new Error(`Malformed task URI: ${uri}`);
+
+        const id = decodeURIComponent(raw);
+        const task = await readTask(context.storage, id);
+        if (task === null) throw new Error(`No task "${id}" on ${context.connection.key}`);
+
+        return { uri, mimeType: 'text/markdown', text: describe(task) };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'list',
+      title: 'List tasks',
+      description:
+        'Tasks the owner has open. Shows in_progress, open and blocked by default — finished, dropped and muted work is excluded unless you name a status, because the question is almost always what is outstanding. Ordered by status, then due date.',
+      inputSchema: z.object({
+        status: z
+          .array(statusSchema)
+          .optional()
+          .describe('Statuses to include. Defaults to in_progress, open and blocked.'),
+        tag: z.string().optional().describe('Restrict to tasks carrying this tag'),
+        query: z.string().optional().describe('Free text to look for in the title, notes, or tags'),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(200)
+          .optional()
+          .describe(`Maximum results (default ${DEFAULT_LIMIT})`),
+      }),
+      // Nothing kept. A task query is as revealing as a memory search: it is
+      // the owner's own material being asked for by name.
+      async handler({ status, tag, query, limit }, context) {
+        const wanted = new Set<TaskStatus>(status ?? ACTIVE_STATUSES);
+        const needle = query?.toLowerCase();
+
+        const all = await allTasks(context.storage);
+        const found = all.filter(
+          (task) =>
+            wanted.has(task.status) &&
+            (!tag || task.tags.includes(tag)) &&
+            (!needle || matches(task, needle)),
+        );
+        const shown = found.slice(0, limit ?? DEFAULT_LIMIT);
+
+        context.audit.annotate({ scanned: all.length, matched: found.length });
+
+        if (shown.length === 0) {
+          const scope = status ? 'matching' : 'outstanding';
+          return {
+            content: [
+              { type: 'text', text: `No ${scope} tasks on ${context.connection.key}.` },
+            ],
+          };
+        }
+
+        // `resource_link` rather than a URI written into the text: core routes
+        // the link to the profile and connection this call was made on, and a
+        // provider must not learn either.
+        return {
+          content: [
+            ...shown.flatMap((task) => [
+              {
+                type: 'resource_link' as const,
+                uri: `tasks://task/${encodeURIComponent(task.id)}`,
+                name: task.title,
+              },
+              { type: 'text' as const, text: `${task.id}  ${line(task)}` },
+            ]),
+            ...(found.length > shown.length
+              ? [
+                  {
+                    type: 'text' as const,
+                    text: `… ${found.length - shown.length} more. Raise limit, or narrow with tag or query.`,
+                  },
+                ]
+              : []),
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      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.',
+      inputSchema: z.object({ id: z.string().min(1).describe('Task id') }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const task = await readTask(context.storage, id);
+
+        if (task === null) {
+          return {
+            content: [{ type: 'text', text: `No task "${id}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        return { content: [{ type: 'text', text: describe(task) }] };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'add',
+      title: 'Add a task',
+      description:
+        'Record something to be done. This is where "remember to…", "add a todo", and "do not let me forget…" belong — not memory, which has no way to say a thing is finished.',
+      inputSchema: z.object({
+        title: z.string().min(1).describe('What is to be done, in one line'),
+        notes: z.string().optional().describe('Detail, as Markdown'),
+        status: statusSchema.optional().describe('Defaults to open'),
+        due: z
+          .string()
+          .optional()
+          .describe('When it is due, as the owner would write it — 2026-09-01, or an instant'),
+        tags: z.array(z.string()).optional().describe('Labels for filtering'),
+        id: z
+          .string()
+          .optional()
+          .describe('Task id. Derived from the title when omitted; naming an existing one replaces it.'),
+      }),
+      // The title and notes are the owner's own words; the rest is the shape of
+      // the change, which is what makes a write log worth having.
+      redact: keepKeys('id', 'status', 'due', 'tags'),
+      async handler({ title, notes, status, due, tags, id }, context) {
+        const taskId = id ?? slugify(title);
+        assertTaskId(taskId);
+
+        const now = new Date().toISOString();
+        const existing = await readTask(context.storage, taskId);
+
+        await writeTask(context.storage, {
+          id: taskId,
+          title,
+          status: status ?? 'open',
+          tags: tags ?? [],
+          ...(due ? { due } : {}),
+          // Preserved across a replace: when a task was first recorded is a fact
+          // about the task, not about the last time something touched it.
+          createdAt: existing?.createdAt ?? now,
+          updatedAt: now,
+          body: notes ?? '',
+        });
+
+        context.audit.annotate({ task: taskId, replaced: existing !== null });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${existing ? 'Replaced' : 'Added'} task "${taskId}" on ${context.connection.key}.`,
+            },
+            { type: 'resource_link', uri: `tasks://task/${taskId}`, name: title },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'update',
+      title: 'Change a task',
+      description:
+        'Change a task in place — most often its status. Marking something done is an update, not a delete: the record of having done it is the useful part. Omitted fields are left as they are.',
+      inputSchema: z.object({
+        id: z.string().min(1).describe('Task id'),
+        status: statusSchema.optional().describe('The new status'),
+        title: z.string().optional().describe('Replaces the title'),
+        notes: z.string().optional().describe('Replaces the notes'),
+        due: z.string().optional().describe('Replaces the due date. Pass "" to clear it.'),
+        tags: z.array(z.string()).optional().describe('Replaces the tags'),
+      }),
+      redact: keepKeys('id', 'status', 'due', 'tags'),
+      async handler({ id, status, title, notes, due, tags }, context) {
+        const existing = await readTask(context.storage, id);
+
+        if (existing === null) {
+          return {
+            content: [{ type: 'text', text: `No task "${id}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        // An explicit empty string clears the date; `undefined` leaves it. The
+        // two are different intentions and a truthiness check would merge them.
+        const nextDue = due === undefined ? existing.due : due === '' ? undefined : due;
+
+        // `due` is pulled off `existing` rather than spread and overwritten,
+        // because spreading cannot *remove* a key: `{ ...existing, ...{} }`
+        // keeps the old date, which is precisely how clearing one silently
+        // failed to clear it.
+        const { due: _previous, ...rest } = existing;
+
+        await writeTask(context.storage, {
+          ...rest,
+          title: title ?? existing.title,
+          status: status ?? existing.status,
+          tags: tags ?? existing.tags,
+          ...(nextDue ? { due: nextDue } : {}),
+          updatedAt: new Date().toISOString(),
+          body: notes ?? existing.body,
+        });
+
+        context.audit.annotate({ task: id, from: existing.status, to: status ?? existing.status });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Updated task "${id}" on ${context.connection.key} — now ${status ?? existing.status}.`,
+            },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'remove',
+      title: 'Delete a task',
+      description:
+        'Remove a task and its notes. For something that was finished or decided against, prefer update with status done or dropped — deleting loses the record that it happened.',
+      inputSchema: z.object({ id: z.string().min(1).describe('Task id') }),
+      redact: keepKeys('id'),
+      async handler({ id }, context) {
+        const existed = await context.storage.has(taskKey(id));
+        await context.storage.delete(taskKey(id));
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: existed
+                ? `Deleted task "${id}" from ${context.connection.key}.`
+                : `No task "${id}" on ${context.connection.key}.`,
+            },
+          ],
+          ...(existed ? {} : { isError: true }),
+        };
+      },
+    },
+  ],
+});
+
+/** One task as a document: the line a list would show, then the notes. */
+function describe(task: Task): string {
+  const header = [
+    `# ${task.title}`,
+    '',
+    `status: ${task.status}`,
+    ...(task.due ? [`due: ${task.due}`] : []),
+    ...(task.tags.length > 0 ? [`tags: ${task.tags.join(', ')}`] : []),
+    `updated: ${task.updatedAt}`,
+  ];
+
+  return task.body.length > 0 ? `${header.join('\n')}\n\n${task.body}` : header.join('\n');
+}
+
+export default tasksProvider;