@lanes-sh/link 0.1.0

package/src/providers/skills/provider.ts

@@ -0,0 +1,283 @@
+import { z } from 'zod';
+import {
+  loadProfileSkills,
+  readSkill,
+  removeSkill,
+  renderSkill,
+  writeSkill,
+  type LoadedSkill,
+} from './store.ts';
+import {
+  defineLocalProvider,
+  keepKeys,
+  type BlobStore,
+  type Capability,
+  type ProviderDefinition,
+} from '#connectivity';
+
+/**
+ * `skills` — reusable procedures, on the MCP prompts primitive.
+ *
+ * **Skills are invoked, not read** (ADR-012 §1). The discriminator is whether
+ * the answer depends on arguments: a resource is a function of its URI alone,
+ * and "review this diff" is a function of the diff. Against a tool: a tool
+ * result returns to the model as data it reasons about, while a prompt returns
+ * as messages that *become* the conversation — and a procedure wants the
+ * second. This is the case ADR-006 reserved the primitive for. That part is
+ * unchanged.
+ *
+ * **What changed is that a skill can now be written (ADR-014).** ADR-012 §1
+ * refused the write path outright: a skill is instructions, so an agent able to
+ * author one could persist its own future behaviour. The argument was right and
+ * the conclusion was too strong. It is the same risk `memory.write` carries —
+ * text an agent authors, stored once, re-served to every later session — and
+ * memory answered it by making writing a separate capability in a non-default
+ * bundle rather than by having no write path at all. Skills now answer it the
+ * same way, and the asymmetry between the two goes away.
+ *
+ * Two things preserve the narrower half of ADR-012 §1:
+ *
+ *   - **Authoring is not in the default bundle.** `lanes link connect skills` grants
+ *     `skills.*`, so narrowing it is a `deny: [skills.manage.*]` line — the
+ *     same one-line narrowing memory documents, and stated as plainly.
+ *   - **`skills.manage.get` is in the write bundle, not the read one.** A
+ *     read-only agent still cannot read a skill body and so cannot select its
+ *     own instructions from one; the prompt primitive's user-selected framing
+ *     survives for every agent that has not been granted authoring.
+ *
+ * The management tools live under `manage.` rather than at the top level
+ * because a skill named `write` would otherwise be the capability
+ * `skills.write` twice over. Skill names cannot contain a dot, so
+ * `skills.manage.*` can only ever mean these four.
+ */
+
+export interface SkillsProviderOptions {
+  /**
+   * The skills currently in the store. Read by the caller because loading them
+   * is asynchronous and building a provider is not, and because the runtime is
+   * the right place to decide when the store is touched.
+   */
+  readonly skills: readonly LoadedSkill[];
+  /**
+   * Where skills live. Omitted for a read-only provider — one built without a
+   * store has no authoring capabilities at all, rather than four that fail.
+   */
+  readonly store?: BlobStore;
+  /**
+   * Called after a write or a removal, so the registry can pick the change up.
+   *
+   * Each skill is its own capability, so a newly written one is invisible until
+   * the provider is rebuilt. The provider cannot rebuild itself and should not
+   * know how; it says that something changed, and the runtime decides what that
+   * means.
+   */
+  readonly onChange?: () => Promise<void>;
+}
+
+export function createSkillsProvider(options: SkillsProviderOptions): ProviderDefinition {
+  const seen = new Set<string>();
+  const capabilities: Capability[] = [];
+
+  for (const skill of options.skills) {
+    if (seen.has(skill.name)) {
+      throw new Error(
+        `Two skills are both named "${skill.name}" (${skill.path}). A skill name becomes the capability id "skills.${skill.name}", which must be unique.`,
+      );
+    }
+    seen.add(skill.name);
+
+    capabilities.push({
+      kind: 'prompt',
+      name: skill.name,
+      ...(skill.title ? { title: skill.title } : {}),
+      description: skill.description,
+      arguments: skill.arguments.map((argument) => ({
+        name: argument.name,
+        description: argument.description,
+        ...(argument.required ? { required: true } : {}),
+      })),
+      // The arguments are the procedure's parameters and are recorded by name
+      // and type only — the default. A skill argument routinely carries the very
+      // material the skill is about.
+      async render(args) {
+        return {
+          messages: [{ role: 'user', text: renderSkill(skill.body, args) }],
+        };
+      },
+    });
+  }
+
+  const manage = options.store ? managementCapabilities(options.store, options.onChange) : [];
+
+  return defineLocalProvider({
+    id: 'skills',
+    name: 'Skills',
+    version: '1.0.0',
+    description:
+      "Reusable procedures the owner has written, offered as MCP prompts. Authoring them is a separate capability from invoking them, and is not granted by default.",
+
+    configSchema: z.object({}),
+    connectionSchema: z.object({}),
+
+    bundles: [
+      {
+        name: 'read',
+        description: 'Invoke the owner-authored skills.',
+        oauth_scopes: [],
+        // Every skill, and nothing that reads or writes a skill's source.
+        // Per-skill control is a policy line — `deny: [skills.review_diff]` —
+        // rather than a bundle.
+        capabilities: [...seen],
+        default: true,
+      },
+      ...(manage.length > 0
+        ? [
+            {
+              // Not in the default bundle, for the reason in the docstring: a
+              // skill an agent writes is instructions it will be handed later.
+              name: 'author',
+              description: 'Read, create, and delete the skills themselves.',
+              oauth_scopes: [],
+              capabilities: manage.map((capability) => capability.name),
+            },
+          ]
+        : []),
+    ],
+
+    capabilities: [...capabilities, ...manage],
+  });
+}
+
+function managementCapabilities(
+  store: BlobStore,
+  onChange: (() => Promise<void>) | undefined,
+): Capability[] {
+  const changed = async (): Promise<void> => {
+    await onChange?.();
+  };
+
+  return [
+    {
+      kind: 'tool',
+      name: 'manage.list',
+      title: 'List skills',
+      description:
+        'Every skill that exists, with its description and arguments. The prompt list shows only the ones policy permits; this shows what is stored.',
+      inputSchema: z.object({}),
+      async handler(_input, context) {
+        const skills = await loadProfileSkills(store);
+
+        if (skills.length === 0) {
+          return { content: [{ type: 'text', text: `No skills on ${context.connection.key}.` }] };
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: skills
+                .map((skill) => {
+                  const args = skill.arguments
+                    .map((argument) => (argument.required ? argument.name : `${argument.name}?`))
+                    .join(', ');
+                  return `${skill.name}${args ? `(${args})` : ''} — ${skill.description}`;
+                })
+                .join('\n'),
+            },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'manage.get',
+      title: 'Read a skill',
+      description:
+        'Return a skill exactly as stored, frontmatter included — what to edit before writing it back.',
+      inputSchema: z.object({
+        name: z.string().min(1).describe('Skill name'),
+      }),
+      redact: keepKeys('name'),
+      async handler({ name }, context) {
+        const skill = await readSkill(store, name);
+
+        if (skill === null) {
+          return {
+            content: [{ type: 'text', text: `No skill "${name}" on ${context.connection.key}.` }],
+            isError: true,
+          };
+        }
+
+        // The stored document, not the parsed body: an edit-then-write round
+        // trip has to carry the frontmatter with it.
+        const bytes = await store.get(skill.path);
+        return {
+          content: [
+            { type: 'text', text: bytes ? new TextDecoder().decode(bytes) : skill.body },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'manage.write',
+      title: 'Write a skill',
+      description:
+        'Create or replace a skill. The text is a whole Markdown document: YAML frontmatter carrying "description" and optional "arguments", then the procedure body, where {{argument}} is substituted at invocation. A skill written here is instructions an agent is later handed as its own turn — this is deliberately a separate capability from invoking one.',
+      inputSchema: z.object({
+        name: z
+          .string()
+          .min(1)
+          .describe('Skill name: lowercase letters, digits, "_" or "-". Becomes skills.<name>.'),
+        text: z.string().min(1).describe('The whole document, frontmatter included'),
+      }),
+      // The name is an address and is worth recording; the text is the
+      // instructions themselves, which are the content rather than the subject.
+      redact: keepKeys('name'),
+      async handler({ name, text }, context) {
+        const skill = await writeSkill(store, name, text);
+        await changed();
+
+        context.audit.annotate({ skill: name, bytes: new TextEncoder().encode(text).byteLength });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Stored skill "${skill.name}" on ${context.connection.key}. It is available as the prompt "skills_${skill.name}" where policy allows it.`,
+            },
+          ],
+        };
+      },
+    },
+
+    {
+      kind: 'tool',
+      name: 'manage.remove',
+      title: 'Delete a skill',
+      description: 'Remove a skill and the prompt it provided.',
+      inputSchema: z.object({
+        name: z.string().min(1).describe('Skill name'),
+      }),
+      redact: keepKeys('name'),
+      async handler({ name }, context) {
+        const removed = await removeSkill(store, name);
+        if (removed) await changed();
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: removed
+                ? `Removed skill "${name}" from ${context.connection.key}.`
+                : `No skill "${name}" on ${context.connection.key}.`,
+            },
+          ],
+          ...(removed ? {} : { isError: true }),
+        };
+      },
+    },
+  ];
+}

package/src/providers/skills/store.ts

@@ -0,0 +1,252 @@
+import type { BlobStore } from '#stores/blobs';
+import { splitFrontmatter } from '#providers/shared/frontmatter.ts';
+import { ConfigError } from '#profile';
+
+/**
+ * Skills the owner has written.
+ *
+ * A skill is a **document in the owner layer's store**, which locally is a file
+ * in `<workspace>/data/<profile>/skills.d/`, in the same format it has always
+ * had. Going through `BlobStore` rather than `node:fs` is what lets a deployed
+ * instance have skills at all: a filesystem path is baked into a container
+ * image at build time, and an S3 key is not.
+ *
+ * **One profile's skills, not the workspace's.** Nothing in this file knows
+ * that — the store it is handed is already rooted at one profile's directory,
+ * which is why moving skills under the profile (ADR-030) changed where the
+ * store is opened and nothing about how it is read.
+ *
+ * Two layouts, because both are conventional and neither is worth refusing:
+ *
+ *     skills.d/review-diff.md
+ *     skills.d/review-diff/SKILL.md
+ *
+ * Frontmatter is YAML between `---` fences, matching every other tool that
+ * reads a skill file. `description` is the only required key; the body after
+ * the fence is the prompt.
+ *
+ * **A skill can now be written, which ADR-012 §1 refused and ADR-014 reverses.**
+ * The reversal is about the *write path existing*, not about who may use it:
+ * authoring stays out of the default bundle, so an agent reaches it only where
+ * policy says so, and the control plane reaches it always.
+ */
+
+/** The nested layout's filename, kept so a rewrite lands on the file it read. */
+const NESTED = 'SKILL.md';
+
+export interface SkillArgument {
+  readonly name: string;
+  readonly description: string;
+  readonly required?: boolean;
+}
+
+export interface LoadedSkill {
+  /** Becomes the capability name, so `skills.<name>` is what policy grants. */
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  readonly arguments: readonly SkillArgument[];
+  readonly body: string;
+  /** The store key it was read from — `review-diff.md` or `review-diff/SKILL.md`. */
+  readonly path: string;
+}
+
+/**
+ * Capability names reach policy rules and MCP wire names, and both are stricter
+ * than a filename. Refused rather than slugified: a skill silently renamed is a
+ * policy rule that silently stops matching.
+ */
+const SKILL_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+
+export function assertSkillName(name: string, source = 'skill'): void {
+  if (!SKILL_NAME.test(name)) {
+    throw new ConfigError(
+      `${source}: skill name ${JSON.stringify(name)} must be lowercase letters, digits, "_" or "-" — ` +
+        'it becomes the capability id "skills.<name>", which policy rules and MCP names both constrain.',
+    );
+  }
+}
+
+/**
+ * Every skill in the store.
+ *
+ * A key that is not a skill is skipped rather than refused — a skill directory
+ * legitimately holds references and scripts beside its `SKILL.md`, and one
+ * unparseable file must not hide every other skill behind it. A file that *is*
+ * a skill and is malformed still throws, because that one is a mistake the
+ * owner wants to hear about.
+ */
+export async function loadProfileSkills(store: BlobStore): Promise<LoadedSkill[]> {
+  const keys = (await store.list()).map((blob) => blob.key).sort();
+  const loaded: LoadedSkill[] = [];
+
+  for (const key of keys) {
+    const name = skillNameFor(key);
+    if (name === null) continue;
+
+    const bytes = await store.get(key);
+    if (bytes === null) continue; // Listed then deleted; not worth failing over.
+
+    loaded.push(parseSkill(new TextDecoder().decode(bytes), key, name));
+  }
+
+  return loaded;
+}
+
+/** Read one skill by name, or null when there is none. */
+export async function readSkill(store: BlobStore, name: string): Promise<LoadedSkill | null> {
+  const key = await skillKey(store, name);
+  if (key === null) return null;
+
+  const bytes = await store.get(key);
+  if (bytes === null) return null;
+
+  return parseSkill(new TextDecoder().decode(bytes), key, name);
+}
+
+/**
+ * Create or replace a skill, validating it before it is stored.
+ *
+ * Parsed first so a malformed document is refused rather than persisted: a
+ * skill that fails to load is invisible until the next start, at which point
+ * the reason it broke is a long way from the write that broke it.
+ *
+ * An existing skill is rewritten **in the layout it already has**, so editing a
+ * `review-diff/SKILL.md` does not silently leave a second `review-diff.md`
+ * beside it — two files claiming one capability id, which the provider refuses
+ * to build at all.
+ *
+ * A *new* one is written as `<name>/SKILL.md`, which is the shape `~/.claude`
+ * uses and the shape the skill bundled with this repository already has. The
+ * flat `<name>.md` still loads and is still rewritten in place; the directory is
+ * the better default because a skill that grows a reference or a script has
+ * somewhere to put it without moving first.
+ */
+export async function writeSkill(
+  store: BlobStore,
+  name: string,
+  text: string,
+): Promise<LoadedSkill> {
+  assertSkillName(name);
+
+  const key = (await skillKey(store, name)) ?? `${name}/${NESTED}`;
+  const skill = parseSkill(text, key, name);
+
+  if (skill.name !== name) {
+    throw new ConfigError(
+      `${key}: the frontmatter names this skill "${skill.name}", but it is being written as "${name}". ` +
+        'Remove the "name" key to take it from the filename, or write it under the name it declares.',
+    );
+  }
+
+  // No contentType: on the filesystem adapter that writes a `<key>.meta`
+  // sidecar, and `skills.d/` is a directory the owner opens and edits by hand.
+  // Nothing reads a skill's stored content type.
+  await store.put(key, new TextEncoder().encode(text));
+  return skill;
+}
+
+/** Delete a skill in whichever layout holds it. Returns false when absent. */
+export async function removeSkill(store: BlobStore, name: string): Promise<boolean> {
+  const key = await skillKey(store, name);
+  if (key === null) return false;
+
+  await store.delete(key);
+  return true;
+}
+
+/** Where a skill of this name lives today, in either layout. */
+async function skillKey(store: BlobStore, name: string): Promise<string | null> {
+  assertSkillName(name);
+
+  const flat = `${name}.md`;
+  if (await store.has(flat)) return flat;
+
+  const nested = `${name}/${NESTED}`;
+  return (await store.has(nested)) ? nested : null;
+}
+
+/**
+ * The skill name a store key implies, or null when the key is not a skill.
+ *
+ * `review-diff.md` and `review-diff/SKILL.md` are skills. A file nested any
+ * deeper, or named anything else inside a skill's own directory, belongs to
+ * that skill and is not one itself.
+ */
+function skillNameFor(key: string): string | null {
+  const segments = key.split('/');
+
+  if (segments.length === 1) {
+    const [file] = segments as [string];
+    return file.endsWith('.md') ? file.slice(0, -'.md'.length) : null;
+  }
+
+  if (segments.length === 2 && segments[1] === NESTED) return segments[0]!;
+  return null;
+}
+
+export function parseSkill(text: string, source: string, fallbackName: string): LoadedSkill {
+  const { frontmatter, body } = splitFrontmatter(text, source);
+
+  const name = typeof frontmatter['name'] === 'string' ? frontmatter['name'] : fallbackName;
+  assertSkillName(name, source);
+
+  const description = frontmatter['description'];
+  if (typeof description !== 'string' || description.trim().length === 0) {
+    throw new ConfigError(
+      `${source}: a skill needs a "description" in its frontmatter. It is the only thing an agent ` +
+        'sees when deciding whether this skill applies.',
+    );
+  }
+
+  if (body.trim().length === 0) {
+    throw new ConfigError(`${source}: the skill has no body, so there is no procedure to render.`);
+  }
+
+  return {
+    name,
+    ...(typeof frontmatter['title'] === 'string' ? { title: frontmatter['title'] } : {}),
+    description,
+    arguments: parseArguments(frontmatter['arguments'], source),
+    body,
+    path: source,
+  };
+}
+
+function parseArguments(raw: unknown, source: string): SkillArgument[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new ConfigError(`${source}: "arguments" must be a list.`);
+  }
+
+  return raw.map((entry, index) => {
+    const record = (entry ?? {}) as Record<string, unknown>;
+    const name = record['name'];
+
+    if (typeof name !== 'string' || !SKILL_NAME.test(name)) {
+      throw new ConfigError(
+        `${source}: arguments[${index}] needs a lowercase "name" — it becomes a prompt argument.`,
+      );
+    }
+
+    return {
+      name,
+      description: typeof record['description'] === 'string' ? record['description'] : name,
+      ...(record['required'] === true ? { required: true } : {}),
+    };
+  });
+}
+
+/**
+ * Substitute `{{argument}}` in a skill body.
+ *
+ * An argument the caller omitted leaves its placeholder in place rather than
+ * becoming an empty string: a procedure that reads "review the diff below" with
+ * nothing below it is a worse failure than one that visibly names what is
+ * missing.
+ */
+export function renderSkill(body: string, args: Readonly<Record<string, string>>): string {
+  return body.replace(/\{\{\s*([a-z0-9_-]+)\s*\}\}/gi, (placeholder, name: string) =>
+    typeof args[name] === 'string' ? args[name]! : placeholder,
+  );
+}