@lanes-sh/link 0.4.1 → 0.5.0

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,
     },

package/src/server/mcp/instructions.ts

@@ -64,6 +64,29 @@ about this person or their work, search it. Writing to memory is a separate
 grant, and what you write is served back to every later session — including to
 a different agent — so write when asked to remember something, not by habit.`;
 
+const TASKS = `**Tasks are what the owner has to do**, each with a status. "Remember to…" and
+"add a todo" belong here. Closing one is an update, not a delete, and a listing
+shows outstanding work unless you ask for more.`;
+
+/**
+ * The pair, when both are reachable — which after ADR-050 is the ordinary case.
+ *
+ * Not the two paragraphs above concatenated. The mistake this is here to prevent
+ * is a routing one — a thing to *do* written into memory, where nothing can ever
+ * close it — and a routing rule is shorter and clearer said once, in one
+ * sentence naming both stores, than implied by two paragraphs that each describe
+ * only themselves. It also very nearly pays for itself: this replaces `MEMORY`
+ * rather than joining it, so the pair costs about what the single one did.
+ */
+const MEMORY_AND_TASKS = `**Memory and tasks are different stores.** Search memory before concluding you do
+not know something about this person or their work. A thing to *do* goes in
+tasks, not memory — "remember to…" is a task, and it has a status. Both are
+served back to every later session, so write when asked, not by habit.`;
+
+const ASSETS = `**Assets are the owner's own files**, kept by name in this profile. Storing one
+names a source, exactly as an attachment does; a text asset reads back as text
+and anything else is described rather than encoded.`;
+
 const SKILLS = `**Skills are the owner's procedures**, surfaced as prompts rather than tools.
 That is deliberate: a procedure is selected by the person, not chosen by the
 model, and you cannot read one's body. They belong to one profile, so a skill
@@ -133,15 +156,39 @@ runs, and a client can report it unreachable while it is up. That is ordinary
 not a fault to diagnose, and not authorization you have lost. Say the call did
 not land, do not redo what already succeeded, and offer to retry.`;
 
-/** Which paragraph each owner-layer provider brings, when it is reachable. */
+/** 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,
 };
 
+/**
+ * The paragraphs this principal should be told, in `RESERVED_PROVIDER_IDS` order.
+ *
+ * A lookup per provider would be enough if every paragraph described exactly one
+ * provider, and one does not: memory and tasks are only worth distinguishing
+ * from each other, so when both are reachable they collapse into one. The
+ * substitution is conditional rather than unconditional for the reason the
+ * docstring at the top of this file gives — prose describing a tool that is not
+ * there is worse than absent prose, and a profile carrying `deny: [tasks.*]` is
+ * exactly the case that would produce it.
+ */
+function habitsFor(reachable: readonly string[]): string[] {
+  const present = new Set(reachable);
+  const paired = present.has('memory') && present.has('tasks');
+
+  return reachable.flatMap((id) => {
+    if (paired && id === 'memory') return [MEMORY_AND_TASKS];
+    if (paired && id === 'tasks') return [];
+    return OWNER_HABITS[id] ? [OWNER_HABITS[id]!] : [];
+  });
+}
+
 /**
  * The whole string's ceiling, and the only budget there is.
  *
@@ -158,11 +205,23 @@ const OWNER_HABITS: Record<string, string> = {
  * Raised a second time, to 2500, for `IDENTITY`, and the same answer for the
  * same reason: an agent signing as the wrong person has already sent the
  * message, and a skill loaded only when relevant is not loaded at the moment
- * that happens. The measured worst case — twenty profiles, twenty connections
- * each, every owner provider reachable, remote clients — is 2474, so this is
- * the measurement plus a little, not a round number picked first. Two things
- * hold it there: the paragraph names no identity, and it is spent only by a
- * profile that declared one.
+ * that happens.
+ *
+ * Raised a third time, to 2700, for tasks and assets (ADR-051), and the answer
+ * is the same shape a third time. The memory/tasks distinction is a routing rule
+ * applied at the instant of a write: an agent that files "remember to chase the
+ * invoice" as a memory entry has put it somewhere nothing can ever close, and it
+ * has already done so by the time a skill would have been loaded. The client
+ * that most needs the rule is the one holding no skills directory.
+ *
+ * The arithmetic, because the number is a measurement and not a round figure:
+ * twenty profiles, twenty connections each, every owner provider reachable,
+ * remote clients, is **2686**. That is the *unpaired* case — memory reachable
+ * and tasks denied — which runs three characters longer than the ordinary one
+ * (2683), because `MEMORY_AND_TASKS` is slightly shorter than `MEMORY` and
+ * `TASKS` apart. Worth stating, because the last two raises were both certified
+ * against a case an endpoint does not actually serve, and the widest case here
+ * is the one that looks like the narrower configuration.
  *
  * Exported because the test asserted `2000` as a literal while the code
  * reserved room against a second, differently-derived number — so the two could
@@ -171,7 +230,7 @@ const OWNER_HABITS: Record<string, string> = {
  * exactly the final length, because `join` adds the same two characters the
  * reduce already counted.
  */
-export const MAX_INSTRUCTIONS = 2500;
+export const MAX_INSTRUCTIONS = 2700;
 
 /** Which of the owner-layer providers this principal can actually reach. */
 function ownerProviders(merged: ReadonlyMap<string, MergedCapability>): string[] {
@@ -238,7 +297,7 @@ export function serverInstructions(
   const sections = [
     OPENING,
     ROUTING,
-    ...owner.map((id) => OWNER_HABITS[id]).filter((habit): habit is string => habit !== undefined),
+    ...habitsFor(owner),
     FILES,
     REFUSAL,
     ...(remoteClients ? [AVAILABILITY] : []),