@lanes-sh/link 0.4.0 → 0.5.0

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;

package/src/providers/tasks/store.ts

@@ -0,0 +1,248 @@
+import type { BlobStore } from '#connectivity';
+import {
+  splitOptionalFrontmatter,
+  stringList,
+  withFrontmatter,
+} from '#providers/shared/frontmatter.ts';
+
+/**
+ * How a task is stored, and the only place that knows.
+ *
+ * **One task is one Markdown file**, exactly as a memory entry is, and for the
+ * same reason: `lanes link tasks` and a text editor reach the same bytes, and
+ * there is no index row that can disagree with the file it describes. ADR-014
+ * reversed that split for memory and there is no argument for reintroducing it
+ * here. The document is frontmatter — title, status, tags, due, timestamps —
+ * above a body that is the notes.
+ *
+ * Its own file rather than living in `provider.ts` because the CLI needs it too
+ * (`lanes link tasks list` reads these bytes) and because the two together
+ * would pass the file-size budget. The seam is the one `skills/` already uses:
+ * this knows the format, the provider knows the capabilities.
+ *
+ * The store arrives scoped to `tasks/<connection>` by core, so nothing here
+ * prefixes a key or thinks about isolation — one connection's tasks are not
+ * addressable from another because of where the store was cut, not because of
+ * anything written below.
+ */
+
+/**
+ * The statuses, in the order a list should show them.
+ *
+ * Six rather than three, and each earns its place by being a different answer
+ * to "why is this not done":
+ *
+ *   in_progress  started, and the thing to pick back up first
+ *   open         not started
+ *   blocked      waiting on something that is not the owner
+ *   muted        deliberately not being surfaced — a real state, and the one
+ *                asked for by name. Distinct from `blocked`: blocked is waiting
+ *                on the world, muted is a decision to stop being reminded.
+ *   done         finished
+ *   dropped      decided against, which is not the same fact as finished and
+ *                should not be recorded as one
+ *
+ * The order is the sort order, which is why it is a tuple rather than a set.
+ */
+export const TASK_STATUSES = [
+  'in_progress',
+  'open',
+  'blocked',
+  'muted',
+  'done',
+  'dropped',
+] as const;
+
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+
+/** The statuses `tasks.list` shows unless asked otherwise. See `provider.ts`. */
+export const ACTIVE_STATUSES: readonly TaskStatus[] = ['in_progress', 'open', 'blocked'];
+
+export interface Task {
+  readonly id: string;
+  readonly title: string;
+  readonly status: TaskStatus;
+  readonly tags: readonly string[];
+  /**
+   * As the owner wrote it — `2026-08-27` or a full instant — never normalised.
+   *
+   * Normalising would have to invent a time zone: "Friday" recorded as an
+   * instant is a different day in two places, and what was typed was a day.
+   * `compareTasks` orders these as strings, which is correct for any ISO-8601
+   * prefix and is the only ordering claim made about them.
+   */
+  readonly due?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly body: string;
+}
+
+const TASK_ID = /^[a-z0-9][a-z0-9_-]*$/;
+
+export function taskKey(id: string): string {
+  return `${id}.md`;
+}
+
+export function idFromKey(key: string): string | null {
+  if (!key.endsWith('.md')) return null;
+  const id = key.slice(0, -'.md'.length);
+  return TASK_ID.test(id) ? id : null;
+}
+
+export function assertTaskId(id: string): void {
+  if (!TASK_ID.test(id)) {
+    throw new Error(
+      `Task id ${JSON.stringify(id)} must be lowercase letters, digits, "_" or "-".`,
+    );
+  }
+}
+
+/** A stable id from a title, so adding a task does not demand one be invented. */
+export function slugify(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+
+  return slug.length > 0 ? slug : `task-${title.length}`;
+}
+
+/**
+ * Parse one stored task, tolerating anything.
+ *
+ * Every field falls back, and none of the fallbacks is an error, because this
+ * reads a directory the owner is invited to edit. A plain Markdown file dropped
+ * in there is an open task titled after its filename — which is a better answer
+ * than an exception that hides every other task behind it. An unrecognised
+ * `status` reads as `open` for the same reason: the useful failure is a task in
+ * the wrong column, not a listing that will not render.
+ */
+export function parseTask(id: string, text: string, fallbackUpdatedAt: string): Task {
+  const { frontmatter, body } = splitOptionalFrontmatter(text);
+
+  const title = frontmatter['title'];
+  const status = frontmatter['status'];
+  const due = frontmatter['due'];
+  const createdAt = frontmatter['created_at'];
+  const updatedAt = frontmatter['updated_at'];
+
+  return {
+    id,
+    title: typeof title === 'string' && title.trim().length > 0 ? title : id,
+    status: readStatus(status),
+    tags: stringList(frontmatter['tags']),
+    ...(typeof due === 'string' && due.trim().length > 0 ? { due } : {}),
+    createdAt: typeof createdAt === 'string' ? createdAt : fallbackUpdatedAt,
+    updatedAt: typeof updatedAt === 'string' ? updatedAt : fallbackUpdatedAt,
+    body: body.trimEnd(),
+  };
+}
+
+/** An unrecognised status is `open`, not an error. See `parseTask`. */
+function readStatus(raw: unknown): TaskStatus {
+  return typeof raw === 'string' && (TASK_STATUSES as readonly string[]).includes(raw)
+    ? (raw as TaskStatus)
+    : 'open';
+}
+
+export function serialiseTask(task: Omit<Task, 'id'>): string {
+  return withFrontmatter(
+    {
+      title: task.title,
+      status: task.status,
+      ...(task.tags.length > 0 ? { tags: [...task.tags] } : {}),
+      ...(task.due ? { due: task.due } : {}),
+      created_at: task.createdAt,
+      updated_at: task.updatedAt,
+    },
+    `${task.body.trimEnd()}\n`,
+  );
+}
+
+export async function readTask(storage: BlobStore, id: string): Promise<Task | null> {
+  const bytes = await storage.get(taskKey(id));
+  if (bytes === null) return null;
+
+  return parseTask(id, new TextDecoder().decode(bytes), new Date(0).toISOString());
+}
+
+export async function writeTask(storage: BlobStore, task: Task): Promise<void> {
+  const { id: _id, ...rest } = task;
+  await storage.put(taskKey(task.id), new TextEncoder().encode(serialiseTask(rest)), {
+    contentType: 'text/markdown',
+  });
+}
+
+/**
+ * How many tasks are read at once.
+ *
+ * The bound memory uses, for the reason memory gives: against a bucket each
+ * read is an HTTPS request, and firing four hundred at once trades a slow list
+ * for a rate-limited one.
+ */
+const READ_CONCURRENCY = 16;
+
+/**
+ * Every task, in the order a list wants them.
+ *
+ * One pass over all of them, and honest about it — the metadata a listing needs
+ * is inside each document, so there is nothing cheaper to consult. That is the
+ * cost of one file per task and it is the same trade memory makes.
+ */
+export async function allTasks(storage: BlobStore): Promise<Task[]> {
+  const blobs = (await storage.list()).flatMap((blob) => {
+    const id = idFromKey(blob.key);
+    return id === null ? [] : [{ blob, id }];
+  });
+
+  const tasks: Task[] = [];
+
+  for (let start = 0; start < blobs.length; start += READ_CONCURRENCY) {
+    const batch = await Promise.all(
+      blobs.slice(start, start + READ_CONCURRENCY).map(async ({ blob, id }) => {
+        const bytes = await storage.get(blob.key);
+        return bytes === null
+          ? null
+          : parseTask(id, new TextDecoder().decode(bytes), blob.modifiedAt.toISOString());
+      }),
+    );
+    for (const task of batch) if (task) tasks.push(task);
+  }
+
+  return tasks.sort(compareTasks);
+}
+
+/**
+ * Status, then due date, then most recently touched.
+ *
+ * Not memory's plain `updatedAt` descending, because a task list is read to
+ * decide what to do next and the most recently *edited* task is rarely that.
+ * Undated sorts after dated within a status: a task with a date is making a
+ * claim about when, and one without is not, so the claim goes first.
+ */
+export function compareTasks(a: Task, b: Task): number {
+  const rank = TASK_STATUSES.indexOf(a.status) - TASK_STATUSES.indexOf(b.status);
+  if (rank !== 0) return rank;
+
+  if (a.due !== b.due) {
+    if (!a.due) return 1;
+    if (!b.due) return -1;
+    return a.due.localeCompare(b.due);
+  }
+
+  return b.updatedAt.localeCompare(a.updatedAt);
+}
+
+/** The pieces `lanes link tasks` needs to reach the same bytes the provider does. */
+export const taskStorage = {
+  key: taskKey,
+  idFromKey,
+  parse: parseTask,
+  serialise: serialiseTask,
+  read: readTask,
+  write: writeTask,
+  all: allTasks,
+  compare: compareTasks,
+  slugify,
+};

package/src/server/mcp/build.ts

@@ -38,7 +38,7 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
       // rather than trusting a copy to stay one. It is the whole endpoint being
       // described, not this connection, so it does not name the profiles the
       // way `title` does.
-      description: 'A self-hostable MCP gateway for all your connections, memory, skills, and secrets',
+      description: 'A self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets',
       websiteUrl: 'https://github.com/lanes-sh/link',
       icons: SERVER_ICONS,
     },