@noodleseed/agent-kit 0.34.0 → 0.36.0

package/skills/codex/examples/gmail-multi-account/README.md

@@ -0,0 +1,46 @@
+# Gmail multi-account automation
+
+**Owns:** The flagship proof that one reusable connector can be bound to multiple independently
+authenticated accounts inside one MCP server.
+
+This fictional example binds `gmailConnector()` twice through separate `externalExchange()` logical
+connections. Public tools always accept `accounts: [...]`; reads accept either account or the canonical
+personal-then-work pair, while mutations accept exactly one account and require runtime confirmation.
+
+Capability slot: **reusable connector + independently authenticated multi-account bindings**. It is distinct
+from `customer-auth`, which owns authentication of the MCP caller rather than downstream connector accounts.
+
+The labels `personal@example.com` and `work@example.com` are static display labels, not provider identities.
+The deployment-owned credential provider maps each logical connection to its real Google authorization.
+No Google client, provider account id, token, or real email address belongs in this project.
+
+## Safety and API boundary
+
+- Search, message/thread reads, draft reads, and vacation-setting reads may target one or both accounts.
+- Draft creation/update/send, label changes, archive, raw send, trash, and vacation updates target one account.
+- Every mutation is prepared against the exact selected binding and must be confirmed before dispatch.
+- `send_message.raw` and draft `raw` are RFC 2822 MIME bytes encoded with base64url. This example does not
+  pretend that `to`/`subject`/`body` strings are sufficient to encode Unicode MIME correctly.
+- Vacation `startTime`/`endTime` schemas enforce only digit-shaped 1–19 character epoch-millisecond strings.
+  When both are supplied, Gmail's backend remains authoritative for the required `startTime < endTime`
+  relationship; this example does not claim cross-field JSON Schema validation.
+- Trash is reversible. Permanent message/thread/draft deletion, delegation, forwarding/sharing settings,
+  and unrestricted raw HTTP requests are intentionally absent.
+
+## Local checks
+
+```sh
+noodle validate
+noodle test
+```
+
+The committed tests compile hermetic fake connector responses. They never contact Gmail or load OAuth
+credentials. A real deployment additionally needs an operator-provided external credential exchange
+endpoint for each logical connection.
+
+## Personal automation skill
+
+The source skill is [`skills/personal-email-automation/SKILL.md`](skills/personal-email-automation/SKILL.md).
+Validate it with the standard skill validator before distribution. The source skill is shipped as part of
+this example; canonical export of an app and its skill as an installable Codex plugin remains roadmap work
+and is not currently provided by Noodle Seed.

package/skills/codex/examples/gmail-multi-account/noodle.json

@@ -0,0 +1,4 @@
+{
+  "entrypoint": "src/server.ts",
+  "name": "gmail-multi-account"
+}

package/skills/codex/examples/gmail-multi-account/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "gmail-multi-account",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "validate": "noodle validate",
+    "dev": "noodle dev",
+    "deploy": "noodle deploy"
+  },
+  "devDependencies": {
+    "@noodleseed/one": "latest",
+    "vitest": "latest"
+  }
+}

package/skills/codex/examples/gmail-multi-account/src/server.ts

@@ -0,0 +1,485 @@
+import {
+  annotations,
+  bind,
+  connection,
+  connector,
+  externalExchange,
+  gmailConnector,
+  server,
+  tool,
+  when,
+  z,
+} from '@noodleseed/one';
+
+export const PERSONAL_ACCOUNT = 'personal@example.com';
+export const WORK_ACCOUNT = 'work@example.com';
+
+const readAccounts = z.union([
+  z.tuple([z.literal(PERSONAL_ACCOUNT)]).and(z.array(z.literal(PERSONAL_ACCOUNT)).length(1)),
+  z.tuple([z.literal(WORK_ACCOUNT)]).and(z.array(z.literal(WORK_ACCOUNT)).length(1)),
+  z
+    .tuple([z.literal(PERSONAL_ACCOUNT), z.literal(WORK_ACCOUNT)])
+    .and(z.array(z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT])).length(2)),
+]);
+const writeAccounts = z.union([
+  z.tuple([z.literal(PERSONAL_ACCOUNT)]).and(z.array(z.literal(PERSONAL_ACCOUNT)).length(1)),
+  z.tuple([z.literal(WORK_ACCOUNT)]).and(z.array(z.literal(WORK_ACCOUNT)).length(1)),
+]);
+const identifier = z.string().min(1);
+const rawMessage = z.string().min(1);
+const labelIds = z.array(identifier).min(1).max(100);
+const epochMillis = z.string().regex(/^\d{1,19}$/);
+const vacationOptionalFields = {
+  restrict_to_contacts: z.boolean().optional(),
+  restrict_to_domain: z.boolean().optional(),
+  start_time: epochMillis.optional(),
+  end_time: epochMillis.optional(),
+};
+const output = z.object({
+  results: z.array(
+    z.object({ account: z.enum([PERSONAL_ACCOUNT, WORK_ACCOUNT]), data: z.unknown() }),
+  ),
+});
+
+const gmail = gmailConnector();
+const personal = connection('personal_gmail', externalExchange());
+const work = connection('work_gmail', externalExchange());
+
+const merge = connector('gmail_account_results')
+  .version('1.0.0')
+  .compute('merge', {
+    type: 'read',
+    input: z.object({
+      personal: z.unknown().optional(),
+      work_first: z.unknown().optional(),
+      work_second: z.unknown().optional(),
+    }),
+    output,
+    run: (input) => {
+      const results: Array<{ account: string; data: unknown }> = [];
+      if (input.personal !== undefined) {
+        results.push({ account: 'personal@example.com', data: input.personal });
+      }
+      const workData = input.work_first ?? input.work_second;
+      if (workData !== undefined) {
+        results.push({ account: 'work@example.com', data: workData });
+      }
+      return { results };
+    },
+  });
+
+const confirmedWrite = annotations.openAction({ destructive: false, confirm: true });
+const confirmedTrash = annotations.openAction({ destructive: true, confirm: true });
+
+export default server(
+  'gmail_multi_account',
+  {
+    title: 'Gmail Multi-Account Automation',
+    version: '1.0.0',
+    use: {
+      personal_gmail: bind(gmail, { profile: 'user_oauth', connection: personal }),
+      work_gmail: bind(gmail, { profile: 'user_oauth', connection: work }),
+      gmail_results: merge,
+    },
+  },
+  [
+    tool('search_messages', {
+      description: 'Search one connected Gmail account or the canonical personal-and-work pair.',
+      input: z.object({
+        accounts: readAccounts,
+        query: z.string(),
+        max_results: z.number().int().min(1).max(500).optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.search_messages({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.search_messages({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.search_messages({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('get_message', {
+      description: 'Get one Gmail message from one connected account or both canonical accounts.',
+      input: z.object({
+        accounts: readAccounts,
+        message_id: identifier,
+        format: z.enum(['minimal', 'full', 'raw', 'metadata']).optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.get_message({
+            message_id: input.message_id,
+            format: input.format,
+          }),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_message({
+            message_id: input.message_id,
+            format: input.format,
+          }),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_message({
+            message_id: input.message_id,
+            format: input.format,
+          }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('get_thread', {
+      description: 'Get one Gmail thread from one connected account or both canonical accounts.',
+      input: z.object({
+        accounts: readAccounts,
+        thread_id: identifier,
+        format: z.enum(['minimal', 'full', 'metadata']).optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.get_thread({
+            thread_id: input.thread_id,
+            format: input.format,
+          }),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_thread({
+            thread_id: input.thread_id,
+            format: input.format,
+          }),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_thread({
+            thread_id: input.thread_id,
+            format: input.format,
+          }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('list_drafts', {
+      description: 'List drafts from one connected Gmail account or both canonical accounts.',
+      input: z.object({
+        accounts: readAccounts,
+        query: z.string().optional(),
+        max_results: z.number().int().min(1).max(500).optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.list_drafts({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.list_drafts({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.list_drafts({
+            q: input.query,
+            maxResults: input.max_results,
+          }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('get_draft', {
+      description: 'Get one draft from one connected Gmail account or both canonical accounts.',
+      input: z.object({
+        accounts: readAccounts,
+        draft_id: identifier,
+        format: z.enum(['minimal', 'full', 'raw', 'metadata']).optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.get_draft({
+            draft_id: input.draft_id,
+            format: input.format,
+          }),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_draft({
+            draft_id: input.draft_id,
+            format: input.format,
+          }),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_draft({
+            draft_id: input.draft_id,
+            format: input.format,
+          }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('get_vacation', {
+      description: 'Read vacation-responder settings from one connected account or both accounts.',
+      input: z.object({ accounts: readAccounts }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.get_vacation({}),
+        );
+        const workFirst = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_vacation({}),
+        );
+        const workSecond = when(input.accounts.at(1).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.get_vacation({}),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: workFirst.data.optional(),
+          work_second: workSecond.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('create_draft', {
+      description:
+        'Create a Gmail draft in exactly one selected account from a base64url MIME message.',
+      annotations: confirmedWrite,
+      input: z.object({ accounts: writeAccounts, raw: rawMessage }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.create_draft({ raw: input.raw }),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.create_draft({ raw: input.raw }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('update_draft', {
+      description:
+        'Replace a Gmail draft in exactly one selected account with a base64url MIME message.',
+      annotations: confirmedWrite,
+      input: z.object({ accounts: writeAccounts, draft_id: identifier, raw: rawMessage }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const args = { draft_id: input.draft_id, raw: input.raw };
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.update_draft(args),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.update_draft(args),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('send_draft', {
+      description: 'Send an existing Gmail draft from exactly one selected account.',
+      annotations: confirmedWrite,
+      input: z.object({ accounts: writeAccounts, draft_id: identifier }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.send_draft({ draft_id: input.draft_id }),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.send_draft({ draft_id: input.draft_id }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('modify_message_labels', {
+      description: 'Add or remove Gmail label ids on one message in exactly one selected account.',
+      annotations: confirmedWrite,
+      input: z.object({
+        accounts: writeAccounts,
+        message_id: identifier,
+        add_label_ids: labelIds.optional(),
+        remove_label_ids: labelIds.optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const args = {
+          message_id: input.message_id,
+          addLabelIds: input.add_label_ids,
+          removeLabelIds: input.remove_label_ids,
+        };
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.modify_message_labels(args),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.modify_message_labels(args),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('archive_message', {
+      description: 'Archive one Gmail message in exactly one account by removing INBOX.',
+      annotations: confirmedWrite,
+      input: z.object({ accounts: writeAccounts, message_id: identifier }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.archive_message({ message_id: input.message_id }),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.archive_message({ message_id: input.message_id }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('send_message', {
+      description: 'Send one base64url MIME message from exactly one selected Gmail account.',
+      annotations: confirmedWrite,
+      input: z.object({
+        accounts: writeAccounts,
+        raw: rawMessage,
+        thread_id: identifier.optional(),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const args = { raw: input.raw, threadId: input.thread_id };
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.send_message(args),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.send_message(args),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('trash_message', {
+      description: 'Move one Gmail message to trash in exactly one account. This is reversible.',
+      annotations: confirmedTrash,
+      input: z.object({ accounts: writeAccounts, message_id: identifier }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.trash_message({ message_id: input.message_id }),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.trash_message({ message_id: input.message_id }),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+    tool('update_vacation', {
+      description: 'Update vacation-responder settings on exactly one selected Gmail account.',
+      annotations: confirmedWrite,
+      input: z.object({
+        accounts: writeAccounts,
+        settings: z.union([
+          z.object({
+            enable_auto_reply: z.literal(false),
+            response_subject: z.string().min(1).optional(),
+            response_body_plain_text: z.string().min(1).optional(),
+            ...vacationOptionalFields,
+          }),
+          z.object({
+            enable_auto_reply: z.literal(true),
+            response_subject: z.string().min(1),
+            response_body_plain_text: z.string().min(1).optional(),
+            ...vacationOptionalFields,
+          }),
+          z.object({
+            enable_auto_reply: z.literal(true),
+            response_subject: z.string().min(1).optional(),
+            response_body_plain_text: z.string().min(1),
+            ...vacationOptionalFields,
+          }),
+        ]),
+      }),
+      output,
+      fulfil: ({ input, connectors }) => {
+        const args = {
+          enableAutoReply: input.settings.enable_auto_reply,
+          responseSubject: input.settings.response_subject,
+          responseBodyPlainText: input.settings.response_body_plain_text,
+          restrictToContacts: input.settings.restrict_to_contacts,
+          restrictToDomain: input.settings.restrict_to_domain,
+          startTime: input.settings.start_time,
+          endTime: input.settings.end_time,
+        };
+        const personal = when(input.accounts.at(0).equals(PERSONAL_ACCOUNT), () =>
+          connectors.personal_gmail.update_vacation(args),
+        );
+        const work = when(input.accounts.at(0).equals(WORK_ACCOUNT), () =>
+          connectors.work_gmail.update_vacation(args),
+        );
+        const merged = connectors.gmail_results.merge({
+          personal: personal.data.optional(),
+          work_first: work.data.optional(),
+        });
+        return { results: merged.results };
+      },
+    }),
+  ],
+);