@lanes-sh/link 0.1.0

package/src/connectivity/manifest/requirements.ts

@@ -0,0 +1,146 @@
+import type { ProviderManifest } from './provider.ts';
+import type { SetupPrompt } from './setup.ts';
+import { credentialRefForConnection } from './credential-ref.ts';
+
+/**
+ * What a provider needs in the credential store before `connect` can finish.
+ *
+ * Derived from the manifest's setup prompts and nothing else — pure, with no
+ * store access — because three callers have to agree on the answer: the
+ * non-interactive preflight in `connect`, `lanes link setup plan`, and the
+ * read-only `setup.provider` capability. If the tool that tells someone what to
+ * run computed this differently from the command they then run, the command
+ * would not work, and the failure would look like a bug in `connect`.
+ *
+ * The split between here and `missingRequirements` is the one that matters:
+ * this file says what setup *requires*, which is a property of shipped code.
+ * Whether a value is *satisfied* needs the credential store, and only the CLI
+ * ever asks that — ADR-007.
+ */
+
+/** The placeholder id used when no connection has been named yet. */
+export const UNNAMED_ID = '<id>';
+
+export interface SetupRequirement {
+  /** Where the value goes. */
+  readonly ref: string;
+  /** What the value is, in the manifest's own words. */
+  readonly label: string;
+  readonly secret: boolean;
+  readonly scope: 'shared' | 'connection';
+  /** The prompt keys this one ref covers — two, for `basic`. */
+  readonly prompts: readonly string[];
+  /** The exact command that stores it. */
+  readonly command: string;
+}
+
+export interface SetupNeeds {
+  readonly requirements: readonly SetupRequirement[];
+  /**
+   * A connection-scoped value cannot be placed without an id.
+   *
+   * The ref derives from the connection id, which `connect` does not settle
+   * until it has asked the provider whose account the credential belongs to.
+   * Without `--id` the ref would be `<provider>/pending`, which is never what
+   * anyone wants — so a non-interactive run has to be told the name up front.
+   */
+  readonly needsId: boolean;
+  /**
+   * The client comes from a broker, so there is nothing here to supply.
+   *
+   * Distinct from an empty `requirements`: a provider that needs nothing and a
+   * provider whose client somebody else operates read the same in a list of
+   * requirements and mean different things to a person deciding what to do
+   * next. A form built from this would render a required field for a value
+   * `connect` will never ask for.
+   */
+  readonly brokered: boolean;
+}
+
+/**
+ * Build the `secrets set` line for one ref.
+ *
+ * Spelled exactly as `secrets set` spells it in its own errors, because a
+ * command someone is told to paste and a command the CLI suggests should not be
+ * two different sentences.
+ */
+function storeCommand(ref: string, placeholder: string, profile: string): string {
+  return `printf %s "${placeholder}" | lanes link secrets set ${ref} --profile ${profile}`;
+}
+
+/** How the value is spelled, for a ref that several prompts combine into. */
+function placeholderFor(prompts: readonly SetupPrompt[]): string {
+  const username = prompts.find((prompt) => prompt.field === 'username');
+  const password = prompts.find((prompt) => prompt.field === 'password');
+
+  // RFC 7617's own encoding, which is what `ensureStaticCredential` writes.
+  // Showing `<value>` here would be a command that stores half a credential.
+  if (username && password) return '<username>:<password>';
+
+  return '<value>';
+}
+
+export function setupRequirements(
+  manifest: ProviderManifest,
+  connectionId: string | undefined,
+  profile: string,
+  options: {
+    /** `oauth_apps` entries this profile declares — the clients that are its own. */
+    readonly ownClients?: readonly string[];
+  } = {},
+): SetupNeeds {
+  const prompts = manifest.setup?.prompts ?? [];
+
+  // A shared prompt exists to collect a client the operator registers. When a
+  // broker supplies one and this profile has not declared its own, there is
+  // nothing to collect — the prompts stay in the manifest because `--own-client`
+  // still needs them, but they are not what this connect will ask for.
+  const brokered =
+    manifest.auth.kind === 'oauth' &&
+    manifest.auth.broker !== undefined &&
+    !(manifest.auth.app !== undefined && (options.ownClients ?? []).includes(manifest.auth.app));
+
+  const shared = brokered ? [] : prompts.filter((prompt) => prompt.scope === 'shared');
+  const perConnection = prompts.filter((prompt) => prompt.scope === 'connection');
+
+  const requirements: SetupRequirement[] = [];
+
+  // A shared prompt names its own ref: nothing about a connection identifies an
+  // OAuth client, so the manifest has to say where it lives.
+  for (const prompt of shared) {
+    if (!prompt.credential_ref) continue;
+    requirements.push({
+      ref: prompt.credential_ref,
+      label: prompt.label,
+      secret: prompt.secret,
+      scope: 'shared',
+      prompts: [prompt.key],
+      command: storeCommand(prompt.credential_ref, '<value>', profile),
+    });
+  }
+
+  // Connection-scoped prompts derive one ref, and `basic` puts two answers in
+  // it. Grouping by the resolved ref rather than emitting one requirement per
+  // prompt is what keeps the emitted command correct for iCloud, where two
+  // separate `secrets set` calls would leave the second overwriting the first.
+  if (perConnection.length > 0) {
+    const ref = credentialRefForConnection(manifest, connectionId ?? UNNAMED_ID);
+
+    if (ref) {
+      requirements.push({
+        ref,
+        label: perConnection.map((prompt) => prompt.label).join(', then '),
+        secret: perConnection.some((prompt) => prompt.secret),
+        scope: 'connection',
+        prompts: perConnection.map((prompt) => prompt.key),
+        command: storeCommand(ref, placeholderFor(perConnection), profile),
+      });
+    }
+  }
+
+  return {
+    requirements,
+    needsId: perConnection.length > 0 && connectionId === undefined,
+    brokered,
+  };
+}

package/src/connectivity/manifest/setup.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { credentialRef } from './primitives.ts';
+
+/**
+ * What the CLI renders before asking for anything.
+ *
+ * The rest of the system stays domain-agnostic because it renders whatever a
+ * provider declares. `docs` alone covers the common "here is where to generate
+ * that key" case with no code at all.
+ */
+
+export const setupPromptSchema = z.object({
+  key: z.string().min(1),
+  label: z.string().min(1),
+  secret: z.boolean().default(false),
+  /**
+   * `shared` — one value for the whole profile, such as an OAuth client. It
+   * needs an explicit ref, because nothing about a connection identifies it.
+   *
+   * `connection` — one value per account, so the ref *derives* and must not be
+   * written: a manifest cannot name a connection that does not exist yet, and a
+   * second copy of the answer could only ever disagree with the first.
+   */
+  scope: z.enum(['shared', 'connection']).default('shared'),
+  /**
+   * Which part of a composite credential this answers.
+   *
+   * `basic` needs two values in one credential and stores them as
+   * `username:password` — RFC 7617's own encoding, so the store holds exactly
+   * what the header carries and nothing has to agree about a JSON shape.
+   */
+  field: z.enum(['value', 'username', 'password']).default('value'),
+  credential_ref: credentialRef.optional(),
+});
+
+export const setupSchema = z.object({
+  summary: z.string().optional(),
+  docs: z.string().optional(),
+  docs_url: z.url().optional(),
+  steps: z.array(z.string()).default([]),
+  prompts: z.array(setupPromptSchema).default([]),
+  /**
+   * One line appended when authentication fails, in the provider's own words.
+   *
+   * A transport can say "the server refused the credential" and no more, because
+   * it must not know which vendor it is talking to. The *provider* knows the
+   * likely cause — for Apple it is nearly always an Account password used where
+   * an app-specific password belongs — and that sentence is worth far more than
+   * the status code. Declared here so the transport stays vendor-free.
+   */
+  troubleshooting: z.string().optional(),
+});
+
+export type SetupDeclaration = z.infer<typeof setupSchema>;
+export type SetupPrompt = z.infer<typeof setupPromptSchema>;

package/src/connectivity/provider.ts

@@ -0,0 +1,163 @@
+import { z } from 'zod';
+import type { SecretRef } from '#secrets';
+import type { Capability } from './capability.ts';
+import type { ProviderContext } from './context.ts';
+import { bundleSchema, defineProvider, type ProviderManifest } from './manifest/index.ts';
+
+/**
+ * Local providers — the only kind that still carries code.
+ *
+ * Everything reachable over MCP or HTTP is a manifest; this exists for
+ * capabilities that *are* ours: `example`, and the M3 owner layer (memory,
+ * skills, vault), which hold no third-party account and could not be expressed
+ * as an upstream call.
+ *
+ * A local provider is a manifest **plus** handlers, so the registry holds one
+ * shape regardless of connectivity.
+ */
+
+/** Local providers hold no third-party account, so this is always `none`. */
+export type AuthRequirement = { readonly kind: 'none' };
+
+export interface ProviderDefinition<
+  ConfigSchema extends z.ZodType = z.ZodType,
+  ConnectionSchema extends z.ZodType = z.ZodType,
+> {
+  readonly manifest: ProviderManifest;
+
+  /** Provider-level settings from the `providers:` block. */
+  readonly configSchema: ConfigSchema;
+  /** Per-connection settings from a `connections:` entry. */
+  readonly connectionSchema: ConnectionSchema;
+
+  readonly capabilities: readonly Capability[];
+
+  /**
+   * Which credential refs a connection may read. Core turns this into the
+   * allowlist behind `ProviderContext.credentials`, so a provider cannot reach
+   * a ref it did not declare.
+   */
+  credentialRefs?(connectionId: string, config: unknown): readonly SecretRef[];
+
+  /** Optional readiness probe surfaced by `doctor`. Never called during dispatch. */
+  healthcheck?(context: ProviderContext): Promise<{ ok: boolean; detail?: string }>;
+}
+
+export interface LocalProviderInput<C extends z.ZodType, N extends z.ZodType> {
+  readonly id: string;
+  readonly name: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly configSchema: C;
+  readonly connectionSchema: N;
+  readonly capabilities: readonly Capability[];
+  readonly bundles?: readonly z.input<typeof bundleSchema>[];
+  readonly redact?: ProviderManifest['redact'];
+  credentialRefs?(connectionId: string, config: unknown): readonly SecretRef[];
+  healthcheck?(context: ProviderContext): Promise<{ ok: boolean; detail?: string }>;
+}
+
+/**
+ * Define a local provider. Validates eagerly, so a malformed one fails at
+ * import rather than at first invocation.
+ */
+export function defineLocalProvider<C extends z.ZodType, N extends z.ZodType>(
+  input: LocalProviderInput<C, N>,
+): ProviderDefinition<C, N> {
+  const seen = new Set<string>();
+  for (const capability of input.capabilities) {
+    if (seen.has(capability.name)) {
+      throw new Error(`Provider ${input.id} declares capability ${capability.name} twice`);
+    }
+    seen.add(capability.name);
+  }
+
+  for (const bundle of input.bundles ?? []) {
+    for (const name of bundle.capabilities ?? []) {
+      // Local bundles name capabilities exactly; globs are for discovered ones,
+      // where we do not know the names in advance.
+      if (!name.includes('*') && !seen.has(name)) {
+        throw new Error(
+          `Provider ${input.id} bundle "${bundle.name}" references unknown capability "${name}"`,
+        );
+      }
+    }
+  }
+
+  const manifest = defineProvider({
+    id: input.id,
+    name: input.name,
+    version: input.version ?? '1.0.0',
+    description: input.description ?? '',
+    connector: { kind: 'local' },
+    auth: { kind: 'none' },
+    ...(input.bundles ? { bundles: input.bundles } : {}),
+    ...(input.redact ? { redact: input.redact } : {}),
+  });
+
+  return {
+    manifest,
+    configSchema: input.configSchema,
+    connectionSchema: input.connectionSchema,
+    capabilities: input.capabilities,
+    ...(input.credentialRefs ? { credentialRefs: input.credentialRefs } : {}),
+    ...(input.healthcheck ? { healthcheck: input.healthcheck } : {}),
+  };
+}
+
+/**
+ * A manifest-based provider that also carries a few capabilities of its own.
+ *
+ * The exception, not the pattern. A provider is a declaration precisely so that
+ * `providers/gmail` can be fifteen lines of data instead of six hundred lines of
+ * endpoint translation, and every capability authored here is a step back
+ * towards the latter. Reach for it only where the vendor's API can do something
+ * its *document* cannot express — the case that forced it is mail, where sending
+ * means handing over one assembled RFC 2822 message and no OpenAPI document
+ * describes composing one, so the generated tool obliges the caller to build it
+ * and therefore to carry the attachment as base64.
+ *
+ * Everything else stays as declared: the connector kind, the auth, the discovered
+ * capabilities. `createCompositeConnector` answers the authored names and
+ * delegates the rest, and the registry adds both sets together with authored
+ * winning a collision.
+ *
+ * There is no `configSchema` or `connectionSchema` argument. Those describe
+ * settings a *local* provider reads from the profile, and a manifest provider's
+ * connection is already described by its manifest — so they are permissive here
+ * rather than inviting a second place to declare the same thing.
+ */
+export function defineProviderWithCapabilities(input: {
+  readonly manifest: ProviderManifest;
+  readonly capabilities: readonly Capability[];
+}): ProviderDefinition {
+  if (input.manifest.connector.kind === 'local') {
+    throw new Error(
+      `Provider "${input.manifest.id}" is a local connector, so it should use defineLocalProvider — there is no remote half to compose with.`,
+    );
+  }
+
+  if (input.capabilities.length === 0) {
+    throw new Error(
+      `Provider "${input.manifest.id}" authors no capabilities, so it is an ordinary manifest — register it directly.`,
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const capability of input.capabilities) {
+    if (seen.has(capability.name)) {
+      throw new Error(
+        `Provider ${input.manifest.id} declares capability ${capability.name} twice`,
+      );
+    }
+    seen.add(capability.name);
+  }
+
+  return {
+    manifest: input.manifest,
+    // Permissive on purpose: see the note above.
+    configSchema: z.unknown(),
+    connectionSchema: z.unknown(),
+    capabilities: input.capabilities,
+  };
+}

package/src/connectivity/transports/README.md

@@ -0,0 +1,33 @@
+# Connectivity types
+
+One folder per way of reaching a service. A provider declares exactly one in its
+manifest's `connector.kind`; how it *authenticates* is the other axis entirely
+(`../auth/`).
+
+| Folder | `connector.kind` | In plain words |
+|---|---|---|
+| `http/` | `http` | a REST API, described by an OpenAPI document |
+| `mcp/` | `mcp` | an upstream MCP server, proxied |
+| `imap/` | `imap` | a mailbox, over IMAP4rev1 and SMTP |
+| `dav/` | `dav` | calendars and contacts, over CalDAV and CardDAV |
+| `fs/` | `fs` | a directory on the machine this runs on |
+| `local/` | `local` | our own code — `example`, and the owner layer |
+
+The folder is named for the `kind:` an operator writes in YAML rather than for
+the friendlier word, because a second name for the same thing is exactly the
+confusion this layout is meant to remove. "api" is `http/`.
+
+## The rule
+
+**Protocol code, not vendor code** (ADR-008). Nothing in here may know that
+iCloud exists. Where a vendor genuinely behaves differently, the difference is a
+field on that transport's schema in `../manifest/connector.ts`, set by the
+provider that needs it — see `fs`'s `placeholder_suffix` and `dav`'s
+`max_range_days`.
+
+## Adding one
+
+A folder here, a member of `connectorSchema` in `../manifest/connector.ts`, and
+a case in `factory.ts`. A transport implements `Connector`: `discover()` says
+what the connection exposes, `invoke()` runs one operation, and `identify()` is
+optional.

package/src/connectivity/transports/composite/index.ts

@@ -0,0 +1,68 @@
+import {
+  type AnyConnector,
+  type CapabilityResult,
+  type ConnectorContext,
+  type DiscoveredCapability,
+  type DiscoveryContext,
+  type ProviderDefinition,
+} from '#connectivity';
+import { createLocalConnector } from '../local/index.ts';
+
+/**
+ * A remote connector with a few capabilities of our own on top.
+ *
+ * Every provider picks one connectivity kind, and that has held for every
+ * provider so far: a manifest describes how to reach a service and the service
+ * describes what it offers. It stops holding when the vendor's API can do
+ * something its *document* cannot express. A mail API is the case in hand — it
+ * accepts a whole assembled RFC 2822 message as one base64 field, and nothing in
+ * an OpenAPI document says "compose MIME from these parts". The generated tool
+ * therefore obliges the caller to build the message, which for anything with an
+ * attachment means emitting the file as base64 into the conversation. That is the
+ * problem this exists to remove.
+ *
+ * Three alternatives were considered and are worse:
+ *
+ * - **Teach the HTTP transport to compose mail.** It is the generic transport;
+ *   mail knowledge in it is vendor knowledge in shared code, which
+ *   `architecture.test.ts` refuses on purpose.
+ * - **A second provider holding just the authored capability.** It would need its
+ *   own connection, so one mailbox would appear twice, consent and identity
+ *   labelling would split, and a policy rule would have to name both.
+ * - **Reach the other provider's credential from a handler.** `ProviderContext`
+ *   says plainly that a provider cannot reach another connection, and that is
+ *   worth more than this feature.
+ *
+ * So: the definition's capabilities are answered here, everything else is
+ * delegated. `discover` delegates untouched, because authored capabilities come
+ * from the definition and must not be written into the discovery cache — they are
+ * code, and caching them would let a stale row outlive a rename.
+ */
+export function createCompositeConnector(input: {
+  readonly definition: ProviderDefinition;
+  readonly remote: AnyConnector;
+}): AnyConnector {
+  const { definition, remote } = input;
+  const authored = createLocalConnector(definition);
+  const names = new Set(definition.capabilities.map((capability) => capability.name));
+
+  return {
+    // The remote kind, because that is what this connection *is*: `doctor`,
+    // `provider list` and the setup walkthrough all describe how the account is
+    // reached, and "composite" would answer a question nobody asked.
+    kind: remote.kind,
+
+    async discover(context: DiscoveryContext): Promise<DiscoveredCapability[]> {
+      return remote.discover(context);
+    },
+
+    async invoke(capability, args, context: ConnectorContext): Promise<CapabilityResult> {
+      return names.has(capability.name)
+        ? authored.invoke(capability, args, context)
+        : remote.invoke(capability, args, context);
+    },
+
+    ...(remote.identify ? { identify: (): Promise<string | null> => remote.identify!() } : {}),
+    ...(remote.close ? { close: (): Promise<void> => remote.close!() } : {}),
+  };
+}

package/src/connectivity/transports/dav/calendar.ts

@@ -0,0 +1,217 @@
+import type { ToolResult } from '#connectivity';
+import { buildEvent, compact, parseEvents, patchEvent } from './ical.ts';
+import { error, json } from './request.ts';
+import { CALDAV, DAV, escapeXml, findAll, parseDav, textOf } from './xml.ts';
+import type { DavClient } from './client.ts';
+
+/**
+ * CalDAV's five operations.
+ *
+ * Free functions over a `DavClient` rather than methods on it, so the class
+ * stays the transport and the feature set stays readable — the two halves were
+ * a 440-line class where the plumbing and the calendar semantics were
+ * interleaved.
+ */
+
+export async function listEvents(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const start = String(args['start'] ?? '');
+    const end = String(args['end'] ?? '');
+    if (!start || !end) return error('start and end are required.');
+
+    const maxDays = dav.maxRangeDays;
+    const span = Date.parse(end) - Date.parse(start);
+    if (Number.isFinite(span) && span > maxDays * 86_400_000) {
+      return error(
+        `That range is longer than ${maxDays} days, which this server refuses. Ask for a narrower window.`,
+      );
+    }
+
+    const limit = Math.min(Number(args['limit'] ?? 50) || 50, 200);
+    const wanted = args['calendar'] ? String(args['calendar']) : undefined;
+
+    const calendars = (await dav.collections()).filter(
+      (collection) => !wanted || collection.name === wanted,
+    );
+    if (calendars.length === 0) {
+      return error(wanted ? `No calendar named "${wanted}".` : 'No calendars in this account.');
+    }
+
+    const from = compact(start);
+    const to = compact(end);
+
+    // `<C:expand>` asks the *server* to turn repeating events into instances,
+    // which is the whole reason there is no recurrence engine in this codebase.
+    const body =
+      `<?xml version="1.0" encoding="utf-8"?>` +
+      `<c:calendar-query xmlns:d="DAV:" xmlns:c="${CALDAV}">` +
+      `<d:prop><d:getetag/>` +
+      `<c:calendar-data><c:expand start="${from}" end="${to}"/></c:calendar-data>` +
+      `</d:prop>` +
+      `<c:filter><c:comp-filter name="VCALENDAR">` +
+      `<c:comp-filter name="VEVENT"><c:time-range start="${from}" end="${to}"/></c:comp-filter>` +
+      `</c:comp-filter></c:filter></c:calendar-query>`;
+
+    const events: unknown[] = [];
+    let expanded = true;
+
+    for (const collection of calendars) {
+      const result = await dav.request(collection.href, 'REPORT', body, { depth: '1' });
+      if (result.status >= 400) continue;
+
+      for (const response of findAll(parseDav(result.text), `{${DAV}}response`)) {
+        const data = textOf(response, `{${CALDAV}}calendar-data`);
+        if (!data) continue;
+
+        for (const event of parseEvents(data)) {
+          // A surviving RRULE means the server ignored `<C:expand>`; say so
+          // rather than presenting a master event as if it were an instance.
+          if (event.recurrence_rule) expanded = false;
+          events.push({ ...event, calendar: collection.name });
+        }
+      }
+    }
+
+    events.sort((a, b) =>
+      String((a as { start?: string }).start ?? '').localeCompare(
+        String((b as { start?: string }).start ?? ''),
+      ),
+    );
+
+    return json({
+      range: { start, end },
+      expanded,
+      ...(expanded
+        ? {}
+        : { note: 'This server did not expand repeating events; those carry recurrence_rule.' }),
+      events: events.slice(0, limit),
+    });
+  }
+
+export async function createEvent(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const name = String(args['calendar'] ?? '');
+    const collection = (await dav.collections()).find((entry) => entry.name === name);
+    if (!collection) return error(`No calendar named "${name}".`);
+
+    const uid = `${crypto.randomUUID()}@lanes-link`;
+    const ical = buildEvent({
+      uid,
+      summary: String(args['summary'] ?? ''),
+      start: String(args['start'] ?? ''),
+      end: String(args['end'] ?? ''),
+      allDay: args['all_day'] === true,
+      location: args['location'] as string | undefined,
+      description: args['description'] as string | undefined,
+      timestamp: new Date().toISOString(),
+    });
+
+    const href = new URL(`${uid}.ics`, `${collection.href.replace(/\/?$/, '/')}`).href;
+
+    const result = await dav.request(href, 'PUT', ical, {
+      'content-type': 'text/calendar; charset=utf-8',
+      // Refuse to overwrite: a UID collision means something is already there,
+      // and silently replacing someone's event is not a create.
+      'if-none-match': '*',
+    });
+
+    if (result.status >= 400) {
+      return error(`The server refused the event (${result.status}). ${result.text.slice(0, 200)}`);
+    }
+
+    return json({ created: true, uid, calendar: name, href });
+  }
+
+  /**
+   * Find one event by UID, and keep hold of its address and ETag.
+   *
+   * The ETag is the whole point. An edit is read-modify-write against a resource
+   * two people may be holding, and `If-Match` is what turns a lost update into a
+   * refusal — without it the second writer wins silently and the first one's
+   * change is simply gone, with no error anywhere.
+   */
+export async function getEvent(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const uid = String(args['uid'] ?? '');
+    const found = await dav.locate(uid, args['calendar'] ? String(args['calendar']) : undefined);
+    if (!found) return error(`No event with UID "${uid}".`);
+
+    const [event] = parseEvents(found.ical);
+    if (!event) return error(`Entry "${uid}" contains no event.`);
+
+    return json({
+      ...event,
+      calendar: found.calendar,
+      ...(args['include_raw'] === true ? { raw: found.ical } : {}),
+    });
+  }
+
+export async function updateEvent(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const uid = String(args['uid'] ?? '');
+    const found = await dav.locate(uid, args['calendar'] ? String(args['calendar']) : undefined);
+    if (!found) return error(`No event with UID "${uid}".`);
+
+    const patched = patchEvent(found.ical, {
+      summary: args['summary'] as string | undefined,
+      start: args['start'] as string | undefined,
+      end: args['end'] as string | undefined,
+      allDay: args['all_day'] as boolean | undefined,
+      location: args['location'] as string | undefined,
+      description: args['description'] as string | undefined,
+      timestamp: new Date().toISOString(),
+    });
+
+    const reply = await dav.request(found.href, 'PUT', patched, {
+      'content-type': 'text/calendar; charset=utf-8',
+      // Not optional. A server with no ETag to match on gets `*`, which at least
+      // refuses to create where we meant to replace.
+      'if-match': found.etag ?? '*',
+    });
+
+    if (reply.status === 412) {
+      return error(
+        `That event changed since it was read, so the edit was refused rather than overwriting someone else's. Read it again and retry.`,
+      );
+    }
+    if (reply.status >= 400) {
+      return error(`The server refused the edit (${reply.status}). ${reply.text.slice(0, 200)}`);
+    }
+
+    const [event] = parseEvents(patched);
+    return json({ updated: true, uid, calendar: found.calendar, event });
+  }
+
+export async function deleteEvent(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const uid = String(args['uid'] ?? '');
+    const found = await dav.locate(uid, args['calendar'] ? String(args['calendar']) : undefined);
+    if (!found) return error(`No event with UID "${uid}".`);
+
+    const reply = await dav.request(found.href, 'DELETE', undefined, {
+      'if-match': found.etag ?? '*',
+    });
+
+    if (reply.status === 412) {
+      return error(
+        `That event changed since it was read, so the deletion was refused. Read it again and retry.`,
+      );
+    }
+    if (reply.status >= 400) {
+      return error(`The server refused the deletion (${reply.status}).`);
+    }
+
+    const [event] = parseEvents(found.ical);
+    return json({ deleted: true, uid, calendar: found.calendar, was: event?.summary ?? null });
+  }
+