@irogane/kaji 0.2.0-beta.11

package/registry/gmail/index.ts

@@ -0,0 +1,165 @@
+// This is YOUR Gmail integration. Edit it.
+
+import {
+  Integration,
+  type MetricsSink,
+  type ToolExecutionContext,
+  type ToolHandler,
+  type ToolSpec,
+  type TraceSink,
+} from "@irogane/kaji";
+import { createGmailRequester } from "@irogane/kaji/integrations";
+
+import { GmailClient } from "./client";
+
+export type SharedGmailClient = Pick<GmailClient, "listMessages" | "getMessage" | "sendMessage">;
+
+function parameters(
+  properties: Readonly<Record<string, unknown>>,
+  required: readonly string[],
+): Record<string, unknown> {
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties,
+    required: [...required],
+    additionalProperties: false,
+  };
+}
+
+function specs(): readonly ToolSpec[] {
+  return [
+    {
+      name: "list_messages",
+      description:
+        "List messages in the authenticated user's mailbox. Pass `page_token` from a prior result's `next_page_token` to page through results.",
+      parameters: parameters(
+        {
+          query: { type: "string", minLength: 1, maxLength: 1_024 },
+          max_results: { type: "integer", minimum: 1, maximum: 100, default: 10 },
+          page_token: { type: "string", minLength: 1, maxLength: 2_048 },
+        },
+        [],
+      ),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+    {
+      name: "get_message",
+      description: "Get a message from the authenticated user's mailbox.",
+      parameters: parameters(
+        {
+          message_id: { type: "string", minLength: 1, maxLength: 128 },
+        },
+        ["message_id"],
+      ),
+      risk: "read",
+      parallel_safe: true,
+      timeout_ms: 10_000,
+    },
+    {
+      name: "send_message",
+      description:
+        "Send an email as the authenticated user. `raw` is the complete RFC 2822 message, base64url-encoded.",
+      parameters: parameters(
+        {
+          raw: { type: "string", minLength: 1, maxLength: 1_048_576 },
+        },
+        ["raw"],
+      ),
+      risk: "external_effect",
+      parallel_safe: false,
+      timeout_ms: 15_000,
+    },
+  ];
+}
+
+function objectResult(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Gmail client returned an invalid tool result");
+  }
+  return value as Record<string, unknown>;
+}
+
+function handler(client: SharedGmailClient, name: string): ToolHandler {
+  return async (args, context) => {
+    switch (name) {
+      case "list_messages":
+        return objectResult(
+          await client.listMessages(context, {
+            ...(args.query === undefined ? {} : { query: args.query as string }),
+            ...(args.max_results === undefined ? {} : { maxResults: args.max_results as number }),
+            ...(args.page_token === undefined ? {} : { pageToken: args.page_token as string }),
+          }),
+        );
+      case "get_message":
+        return objectResult(
+          await client.getMessage(context, { messageId: args.message_id as string }),
+        );
+      case "send_message":
+        return objectResult(await client.sendMessage(context, { raw: args.raw as string }));
+      default:
+        throw new Error("Unknown Gmail tool");
+    }
+  };
+}
+
+export function createSharedGmailToolBindings(
+  client: SharedGmailClient,
+): [ToolSpec, ToolHandler][] {
+  return specs().map((spec) => [spec, handler(client, spec.name)]);
+}
+
+export class GmailIntegration extends Integration {
+  readonly namespace = "gmail";
+  private closeOwnedRequester: (() => void) | undefined;
+
+  constructor(
+    private readonly client: SharedGmailClient,
+    closeOwnedRequester?: () => void,
+  ) {
+    super();
+    this.closeOwnedRequester = closeOwnedRequester;
+  }
+
+  override tools(): [ToolSpec, ToolHandler][] {
+    return createSharedGmailToolBindings(this.client);
+  }
+
+  close(): void {
+    const close = this.closeOwnedRequester;
+    if (close === undefined) return;
+    close();
+    this.closeOwnedRequester = undefined;
+  }
+}
+
+export interface CreateGmailIntegrationOptions {
+  readonly tokenFor: (context: ToolExecutionContext) => Promise<string>;
+  readonly metricsSink?: MetricsSink;
+  readonly traceSink?: TraceSink;
+}
+
+export function createGmailIntegration(options: CreateGmailIntegrationOptions): GmailIntegration {
+  const { metricsSink, traceSink, ...clientOptions } = options;
+  const http = createGmailRequester({ metricsSink, traceSink });
+  return new GmailIntegration(new GmailClient({ ...clientOptions, http }), () => http.close());
+}
+
+function createGmailIntegrationForTest(client: SharedGmailClient): GmailIntegration {
+  return new GmailIntegration(client);
+}
+
+const inspectionClient = new Proxy(
+  {},
+  {
+    get: () => async () => {
+      throw new Error("inspection dependencies must not execute");
+    },
+  },
+) as SharedGmailClient;
+
+export function inspectIntegration(): GmailIntegration {
+  return createGmailIntegrationForTest(inspectionClient);
+}

package/registry/gmail/manifest.json

@@ -0,0 +1,102 @@
+{
+  "name": "gmail",
+  "version": "0.1.0",
+  "namespace": "gmail",
+  "description": "Mailbox-scoped Gmail read and send tools for the authenticated user.",
+  "auth": {
+    "kind": "oauth",
+    "provider": "google",
+    "clientIdEnv": "GOOGLE_CLIENT_ID",
+    "clientSecretEnv": "GOOGLE_CLIENT_SECRET",
+    "scopes": [
+      "https://www.googleapis.com/auth/gmail.readonly",
+      "https://www.googleapis.com/auth/gmail.send"
+    ],
+    "docs": "https://developers.google.com/gmail/api/auth/scopes"
+  },
+  "files": [
+    "index.ts",
+    "client.ts",
+    "tests/gmail.test.ts",
+    "owner-fixtures.json",
+    "LICENSE"
+  ],
+  "tools": [
+    {
+      "name": "get_message",
+      "description": "Get a message from the authenticated user's mailbox.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "message_id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 128
+          }
+        },
+        "required": [
+          "message_id"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    },
+    {
+      "name": "list_messages",
+      "description": "List messages in the authenticated user's mailbox. Pass `page_token` from a prior result's `next_page_token` to page through results.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1024
+          },
+          "max_results": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 100,
+            "default": 10
+          },
+          "page_token": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2048
+          }
+        },
+        "required": [],
+        "additionalProperties": false
+      },
+      "risk": "read",
+      "parallel_safe": true,
+      "timeout_ms": 10000
+    },
+    {
+      "name": "send_message",
+      "description": "Send an email as the authenticated user. `raw` is the complete RFC 2822 message, base64url-encoded.",
+      "parameters": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "raw": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1048576
+          }
+        },
+        "required": [
+          "raw"
+        ],
+        "additionalProperties": false
+      },
+      "risk": "external_effect",
+      "parallel_safe": false,
+      "timeout_ms": 15000
+    }
+  ],
+  "peerDeps": {}
+}

package/registry/gmail/owner-fixtures.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": "1.0.0",
+  "outcomes": [
+    { "name": "success", "expected": "success" },
+    { "name": "missing_auth", "expected": "INTEGRATION_AUTH_REQUIRED" },
+    { "name": "rate_limit", "expected": "INTEGRATION_RATE_LIMITED" },
+    { "name": "approval_rejected", "expected": "APPROVAL_REJECTED" },
+    { "name": "connection_lost_after_dispatch", "expected": "unknown" }
+  ]
+}

package/registry/gmail/tests/gmail.test.ts

@@ -0,0 +1,32 @@
+// This is YOUR no-network Gmail owner fixture test. Edit it.
+
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const closedOutcomes = new Set([
+  "success",
+  "missing_auth",
+  "rate_limit",
+  "approval_rejected",
+  "connection_lost_after_dispatch",
+]);
+
+export function scriptedOutcome(name: string): string {
+  if (!closedOutcomes.has(name)) throw new Error("unknown scripted Gmail outcome");
+  const fixture = JSON.parse(
+    readFileSync(new URL("../owner-fixtures.json", import.meta.url), "utf8"),
+  ) as { outcomes: Array<{ name: string; expected: string }> };
+  return fixture.outcomes.find((row) => row.name === name)!.expected;
+}
+
+describe("Gmail owner fixtures", () => {
+  it("keeps scripted outcomes closed and network-free", () => {
+    expect([...closedOutcomes].map((name) => [name, scriptedOutcome(name)])).toEqual([
+      ["success", "success"],
+      ["missing_auth", "INTEGRATION_AUTH_REQUIRED"],
+      ["rate_limit", "INTEGRATION_RATE_LIMITED"],
+      ["approval_rejected", "APPROVAL_REJECTED"],
+      ["connection_lost_after_dispatch", "unknown"],
+    ]);
+  });
+});

package/registry/index.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "./index.schema.json",
+  "version": "0.1.0",
+  "integrations": {
+    "echo": {
+      "manifest": "echo/manifest.json",
+      "stability": "beta",
+      "runtimes": ["python", "typescript"]
+    },
+    "gmail": {
+      "manifest": "gmail/manifest.json",
+      "stability": "beta",
+      "runtimes": ["python", "typescript"]
+    },
+    "github": {
+      "manifest": "github/manifest.json",
+      "stability": "beta",
+      "runtimes": ["python", "typescript"]
+    }
+  }
+}

package/registry/index.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/schemas/integration-index-v1.json",
+  "title": "Kaji integration registry index",
+  "type": "object",
+  "required": ["$schema", "version", "integrations"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "const": "./index.schema.json" },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "integrations": {
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z][a-z0-9_-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["manifest", "stability", "runtimes"],
+        "additionalProperties": false,
+        "properties": {
+          "manifest": {
+            "type": "string",
+            "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.\\.?(?:/|$))[A-Za-z0-9_@.+-]+(?:/[A-Za-z0-9_@.+-]+)*$"
+          },
+          "stability": { "enum": ["experimental", "beta"] },
+          "runtimes": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "enum": ["python", "typescript"] }
+          }
+        }
+      }
+    }
+  }
+}

package/registry/schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kaji.dev/schemas/integration-manifest-v1.json",
+  "title": "Kaji integration manifest",
+  "type": "object",
+  "required": ["name", "version", "namespace", "description", "auth", "files", "tools"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^[a-z][a-z0-9_-]*$"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "auth": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["kind"],
+          "properties": {
+            "kind": { "const": "none" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "env"],
+          "properties": {
+            "kind": { "const": "env" },
+            "env": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]*$"
+            },
+            "optional": { "type": "boolean", "default": false },
+            "docs": { "type": "string", "format": "uri" }
+          },
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "required": ["kind", "provider", "clientIdEnv", "scopes"],
+          "properties": {
+            "kind": { "const": "oauth" },
+            "provider": { "enum": ["google"] },
+            "clientIdEnv": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]*$"
+            },
+            "clientSecretEnv": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]*$"
+            },
+            "scopes": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "type": "string", "minLength": 1, "maxLength": 512 }
+            },
+            "docs": { "type": "string", "format": "uri" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(?!/)(?![A-Za-z]:)(?!.*\\\\)(?!.*(?:^|/)\\.\\.?(?:/|$))[A-Za-z0-9_@.+-]+(?:/[A-Za-z0-9_@.+-]+)*$"
+      }
+    },
+    "tools": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "parameters", "risk", "parallel_safe"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$"
+          },
+          "description": { "type": "string", "minLength": 1 },
+          "parameters": { "type": "object" },
+          "risk": {
+            "enum": ["read", "write", "external_effect", "destructive", "admin"]
+          },
+          "parallel_safe": { "type": "boolean" },
+          "timeout_ms": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "extras": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "peerDeps": {
+      "type": "object",
+      "propertyNames": { "minLength": 1 },
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    }
+  }
+}