@capybara-hq/testing 0.0.0-stage → 0.1.0-rc.0

package/fixtures/extensions/fake-im/src/index.ts

@@ -0,0 +1,91 @@
+import {
+  defineExtension,
+  secret,
+  ToolError,
+  type ToolHandler,
+  type ToolSpec,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { makeFakeImChannel } from "./channel.js";
+import { FakeImOrgConfig, fakeImDirectory } from "./directory.js";
+import { fakeImIdentitySource } from "./identity.js";
+
+export { FakeImConnection, fakeImWebhook, makeFakeImChannel } from "./channel.js";
+export { FakeImOrgConfig, fakeImDirectory } from "./directory.js";
+export { fakeImIdentitySource } from "./identity.js";
+
+/** 部署级配置：平台地址与登录用的 OAuth 客户端（clientSecret 走密钥存储）。 */
+const Deployment = z.object({
+  platformUrl: z.string().url(),
+  tenant: z.string().min(1).default("t1"),
+  clientId: z.string().min(1),
+  clientSecret: secret(z.string().min(1)),
+});
+export type FakeImDeployment = z.infer<typeof Deployment>;
+
+const PostInput = z.object({ text: z.string().min(1).max(500) });
+
+/** 写工具：在平台上发一条公告。默认策略 ask（每次调用都要发起人批准）。 */
+const POST_SPEC: ToolSpec = {
+  name: "post_announcement",
+  description:
+    "Post an announcement to the company-wide channel on the IM platform. Everyone in the " +
+    "company sees it, so only use it when the user explicitly asks to announce something.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: { type: "string", minLength: 1, maxLength: 500, description: "Announcement text." },
+    },
+    required: ["text"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  defaultPolicy: "ask",
+};
+
+const postHandler =
+  (config: () => FakeImDeployment): ToolHandler =>
+  async (input, ctx) => {
+    const parsed = PostInput.safeParse(input);
+    if (!parsed.success) {
+      throw new ToolError("Invalid input: pass a non-empty text of at most 500 characters.");
+    }
+    const res = await fetch(`${config().platformUrl}/posts`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-pid": String(process.pid) },
+      body: JSON.stringify({ text: parsed.data.text, conversationId: ctx.conversationId }),
+      signal: ctx.signal,
+    });
+    if (res.status !== 200) {
+      await res.body?.cancel();
+      throw new ToolError("The IM platform rejected the announcement; retry later.", {
+        kind: "unavailable",
+      });
+    }
+    const { id } = (await res.json()) as { id: string };
+    return { content: [{ type: "text", text: `Announcement posted (${id}).` }] };
+  };
+
+/**
+ * 假 IM 平台的完整测试插件（连 `@capybara-hq/testing` 的 startFakeChannelServer）：
+ * `channel@1`（机器人）+ `identity-source@1`（登录）+ `directory@1`（通讯录），另带一个默认需要批准的写工具。
+ * 三处的身份源键都是 `fake-im:<租户>`，同一个人只对应一行身份。T15–T18 的真实渠道插件照这个形状写。
+ */
+export default defineExtension({
+  name: "fake-im",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: ["channel@1", "identity-source@1", "directory@1"],
+  permissions: { tools: ["post_announcement"] },
+  config: { deployment: Deployment, org: FakeImOrgConfig },
+  setup(ctx) {
+    const config = () => Deployment.parse(ctx.config);
+    ctx.provide(
+      "channel@1",
+      makeFakeImChannel({ cards: true, edit: true, threads: true }, { webhook: true }),
+    );
+    ctx.provide("identity-source@1", fakeImIdentitySource);
+    ctx.provide("directory@1", fakeImDirectory);
+    ctx.tools.register(POST_SPEC, postHandler(config));
+  },
+});

package/fixtures/extensions/fake-object-store/.capybara-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-object-store",
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: object-store@1 backed by the startTestS3 container"
+}

package/fixtures/extensions/fake-object-store/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-object-store",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: object-store@1 backed by the startTestS3 container",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "@aws-sdk/client-s3": "^3.1154.0",
+    "@aws-sdk/s3-presigned-post": "^3.1154.0",
+    "@aws-sdk/s3-request-presigner": "^3.1154.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-object-store/src/index.ts

@@ -0,0 +1,210 @@
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client,
+  S3ServiceException,
+} from "@aws-sdk/client-s3";
+import { createPresignedPost } from "@aws-sdk/s3-presigned-post";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import {
+  defineExtension,
+  OBJECT_STORE_EXTENSION_POINT,
+  type ObjectHead,
+  type ObjectStore,
+  secret,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+/**
+ * Test fake of an object store extension (`object-store@1`) backed by the S3 container of
+ * `startTestS3()` (SeaweedFS). It exists so core tests do not load the official object store; it
+ * implements what the kernel relies on and no more: the deployment config has the same shape as
+ * `startTestS3()` returns (`endpoint`, `region`, `bucket`, secret `accessKeyId` /
+ * `secretAccessKey`, `forcePathStyle`), streams are buffered in memory (test objects are small),
+ * `presignPut` is a POST policy whose size and type the store enforces, keys containing `${` are
+ * refused, `presignGet` sets the disposition and response type.
+ */
+
+const DeploymentConfig = z.object({
+  endpoint: z.string().url().optional(),
+  region: z.string().min(1),
+  bucket: z.string().min(1),
+  accessKeyId: secret(z.string().min(1)),
+  secretAccessKey: secret(z.string().min(1)),
+  forcePathStyle: z.boolean().default(true),
+});
+
+/** The deployment config of the fake (as `startTestS3()` gives it). */
+export type FakeObjectStoreConfig = z.input<typeof DeploymentConfig>;
+
+const PAGE_MAX = 1000;
+
+const isNotFound = (e: unknown): boolean =>
+  e instanceof S3ServiceException &&
+  (e.name === "NotFound" || e.name === "NoSuchKey" || e.$metadata.httpStatusCode === 404);
+
+const etag = (v: string | undefined) => (v ? { etag: v.replaceAll('"', "") } : {});
+
+/** `Content-Range: bytes 0-4/11` -> 11. */
+const totalFromRange = (range: string | undefined): number | undefined => {
+  const m = range?.match(/\/(\d+)$/);
+  return m ? Number(m[1]) : undefined;
+};
+
+/** RFC 6266 disposition with an ASCII fallback and the UTF-8 `filename*`. */
+const contentDisposition = (disposition: string, name: string | undefined): string =>
+  name === undefined
+    ? disposition
+    : `${disposition}; filename="${name.replace(/[^\x20-\x7e]|["\\%]/g, "_")}"; filename*=UTF-8''${encodeURIComponent(name)}`;
+
+const emptyStream = () =>
+  new ReadableStream<Uint8Array>({
+    start(c) {
+      c.close();
+    },
+  });
+
+/** Creates the S3-backed store (exported for tests that use it without a kernel). */
+export function createFakeObjectStore(input: FakeObjectStoreConfig): ObjectStore {
+  const cfg = DeploymentConfig.parse(input);
+  const client = new S3Client({
+    region: cfg.region,
+    credentials: { accessKeyId: cfg.accessKeyId, secretAccessKey: cfg.secretAccessKey },
+    forcePathStyle: cfg.forcePathStyle,
+    ...(cfg.endpoint !== undefined && { endpoint: cfg.endpoint }),
+    requestChecksumCalculation: "WHEN_REQUIRED",
+    responseChecksumValidation: "WHEN_REQUIRED",
+  });
+  const Bucket = cfg.bucket;
+  return {
+    async put(key, body, opts) {
+      const data =
+        body instanceof Uint8Array ? body : new Uint8Array(await new Response(body).arrayBuffer());
+      const r = await client.send(
+        new PutObjectCommand({ Bucket, Key: key, Body: data, ContentType: opts.contentType }),
+        opts.signal ? { abortSignal: opts.signal } : {},
+      );
+      return { key, size: data.byteLength, contentType: opts.contentType, ...etag(r.ETag) };
+    },
+    async get(key, opts) {
+      const range = opts?.range;
+      try {
+        const r = await client.send(
+          new GetObjectCommand({
+            Bucket,
+            Key: key,
+            ...(range !== undefined && { Range: `bytes=${range.start}-${range.end ?? ""}` }),
+          }),
+          opts?.signal ? { abortSignal: opts.signal } : {},
+        );
+        const head: ObjectHead = {
+          key,
+          size: totalFromRange(r.ContentRange) ?? r.ContentLength ?? 0,
+          contentType: r.ContentType ?? "application/octet-stream",
+          ...etag(r.ETag),
+        };
+        const stream = r.Body?.transformToWebStream() as ReadableStream<Uint8Array> | undefined;
+        return { head, body: stream ?? emptyStream() };
+      } catch (e) {
+        if (isNotFound(e)) return null;
+        throw e;
+      }
+    },
+    async head(key) {
+      try {
+        const r = await client.send(new HeadObjectCommand({ Bucket, Key: key }));
+        return {
+          key,
+          size: r.ContentLength ?? 0,
+          contentType: r.ContentType ?? "application/octet-stream",
+          ...etag(r.ETag),
+        };
+      } catch (e) {
+        if (isNotFound(e)) return null;
+        throw e;
+      }
+    },
+    async delete(key) {
+      await client.send(new DeleteObjectCommand({ Bucket, Key: key }));
+    },
+    async deletePrefix(prefix) {
+      let deleted = 0;
+      for (;;) {
+        const page = await client.send(
+          new ListObjectsV2Command({ Bucket, Prefix: prefix, MaxKeys: PAGE_MAX }),
+        );
+        const keys = (page.Contents ?? []).flatMap((o) => (o.Key ? [o.Key] : []));
+        if (keys.length === 0) return deleted;
+        for (const Key of keys) await client.send(new DeleteObjectCommand({ Bucket, Key }));
+        deleted += keys.length;
+      }
+    },
+    async list(prefix, opts) {
+      const r = await client.send(
+        new ListObjectsV2Command({
+          Bucket,
+          Prefix: prefix,
+          MaxKeys: Math.min(Math.max(1, opts?.limit ?? PAGE_MAX), PAGE_MAX),
+          ...(opts?.cursor !== undefined && { ContinuationToken: opts.cursor }),
+        }),
+      );
+      const items: ObjectHead[] = (r.Contents ?? []).flatMap((o) =>
+        o.Key === undefined ? [] : [{ key: o.Key, size: o.Size ?? 0, contentType: "" }],
+      );
+      return r.IsTruncated && r.NextContinuationToken
+        ? { items, cursor: r.NextContinuationToken }
+        : { items };
+    },
+    async presignGet(key, opts) {
+      return getSignedUrl(
+        client,
+        new GetObjectCommand({
+          Bucket,
+          Key: key,
+          ResponseContentDisposition: contentDisposition(
+            opts.disposition ?? "attachment",
+            opts.downloadName,
+          ),
+          ...(opts.responseContentType !== undefined && {
+            ResponseContentType: opts.responseContentType,
+          }),
+        }),
+        { expiresIn: opts.ttlSeconds },
+      );
+    },
+    async presignPut(key, opts) {
+      if (key.includes("${")) {
+        throw new Error("fake-object-store: presignPut key must not contain '${'");
+      }
+      const { url, fields } = await createPresignedPost(client, {
+        Bucket,
+        Key: key,
+        Conditions: [
+          { key },
+          ["content-length-range", 0, opts.maxSize],
+          ["eq", "$Content-Type", opts.contentType],
+        ],
+        Fields: { "Content-Type": opts.contentType },
+        Expires: opts.ttlSeconds,
+      });
+      return { method: "POST", url, headers: {}, fields };
+    },
+  };
+}
+
+export default defineExtension({
+  name: "fake-object-store",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [OBJECT_STORE_EXTENSION_POINT],
+  config: { deployment: DeploymentConfig },
+  setup(ctx) {
+    ctx.provide(
+      OBJECT_STORE_EXTENSION_POINT,
+      createFakeObjectStore(ctx.config as FakeObjectStoreConfig),
+    );
+  },
+});

package/fixtures/extensions/fake-openapi/.capybara-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-openapi",
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: connector@1 of kind openapi, reading a small JSON operations document"
+}

package/fixtures/extensions/fake-openapi/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-openapi",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: connector@1 of kind openapi, reading a small JSON operations document",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-openapi/src/index.ts

@@ -0,0 +1,258 @@
+import {
+  type AuthHint,
+  CONNECTOR_EXTENSION_POINT,
+  type Connector,
+  type ConnectorInspection,
+  type ConnectorOpenArgs,
+  type ConnectorSession,
+  defineExtension,
+  ToolError,
+  type ToolResult,
+  type ToolSpec,
+} from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+/**
+ * Test fake of an OpenAPI-style connector extension (`connector@1`, kind `openapi`): the kind the
+ * web install wizard drives with a spec URL, an auth step prefilled from the document's security
+ * schemes and an operations table. It stands in for the official `connector-openapi` in core's
+ * tests (the web e2e loads it next to `fake-connector`, which is kind `mcp` there; one extension
+ * provides an extension point once, so the two kinds need two fakes). It reads a small JSON
+ * document instead of OpenAPI:
+ *
+ * ```json
+ * { "securitySchemes": { "<scheme>": { "type": "api_key", "in": "header", "name": "X-API-Key" } },
+ *   "baseUrl": "https://…",
+ *   "operations": [{ "name": "createPet", "method": "POST", "path": "/pets", "summary": "…",
+ *                    "annotations": { "readOnlyHint": false } }] }
+ * ```
+ *
+ * - `endpointSchema`: `{ specUrl, baseUrl?, operations? }` (the wizard's OpenAPI endpoint without
+ *   `specText`), https or (with `allowInsecureLoopback`, default on) loopback http;
+ * - `inspect`: the document's security schemes as auth hints (`{ scheme, ...value }`) and its
+ *   operations (`id` = name);
+ * - a session lists one tool per operation (all, or the endpoint's `operations`), named by the
+ *   operation, with input `{ body? }` and `connectorData` `{ method, path }`; a call sends the
+ *   method to `baseUrl` (endpoint, else document, else the spec URL's origin) + path with `auth()`
+ *   injected (one `onUnauthorized()` + retry on 401), the JSON `body`, and no redirects. A 4xx is a
+ *   tool error result (`HTTP <status>: <body>`); a 5xx or an unreachable server is a ToolError of
+ *   kind `unavailable`.
+ */
+
+const DeploymentConfig = z.object({
+  /** Accept http://127.0.0.1 / localhost / [::1] URLs (on by default: this is a test fake). */
+  allowInsecureLoopback: z.boolean().default(true),
+});
+
+const isLoopbackHttp = (u: URL): boolean =>
+  u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname);
+
+const urlOk = (raw: string, loopback: boolean): boolean => {
+  try {
+    const u = new URL(raw);
+    return u.protocol === "https:" || (loopback && isLoopbackHttp(u));
+  } catch {
+    return true; // z.url() reports the format error
+  }
+};
+
+/** The endpoint: the document URL, an optional API base URL and the selected operations. */
+export function fakeOpenApiEndpointSchema(allowInsecureLoopback: boolean) {
+  const url = z.url().refine((v) => urlOk(v, allowInsecureLoopback), {
+    message: "URL must use https (plain http only for loopback hosts)",
+  });
+  return z
+    .object({
+      specUrl: url,
+      baseUrl: url.optional(),
+      operations: z.array(z.string().min(1)).optional(),
+    })
+    .strict();
+}
+
+type Endpoint = z.infer<ReturnType<typeof fakeOpenApiEndpointSchema>>;
+
+const Scheme = z.union([
+  z.object({ type: z.literal("api_key"), in: z.enum(["header", "query"]), name: z.string() }),
+  z.object({ type: z.literal("bearer") }),
+  z.object({ type: z.literal("basic") }),
+]);
+
+const Operation = z.object({
+  name: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/),
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+  path: z.string().startsWith("/"),
+  summary: z.string().optional(),
+  annotations: z
+    .object({
+      readOnlyHint: z.boolean().optional(),
+      destructiveHint: z.boolean().optional(),
+      idempotentHint: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+const Doc = z.object({
+  securitySchemes: z.record(z.string(), Scheme).default({}),
+  baseUrl: z.url().optional(),
+  operations: z.array(Operation),
+});
+
+type Doc = z.infer<typeof Doc>;
+
+const UNREACHABLE_TEXT = "Could not reach the connector's server; retry later.";
+const AUTH_FAILED_TEXT = "Authentication failed for this connector; ask the user to reconnect it.";
+
+/** Reads the operations document (no credentials: like an OpenAPI document, it is public). */
+async function loadDoc(endpoint: Endpoint, signal: AbortSignal): Promise<Doc> {
+  let res: Response;
+  try {
+    res = await fetch(endpoint.specUrl, { signal, redirect: "manual" });
+  } catch {
+    throw new ToolError(UNREACHABLE_TEXT, { kind: "unavailable" });
+  }
+  if (!res.ok) {
+    await res.body?.cancel();
+    throw new ToolError(`The spec URL answered HTTP ${res.status}; check the endpoint.`);
+  }
+  const parsed = Doc.safeParse(await res.json().catch(() => undefined));
+  if (!parsed.success) {
+    throw new ToolError(
+      "The spec URL did not return a valid operations document; check the endpoint's specUrl.",
+    );
+  }
+  return parsed.data;
+}
+
+const hintsOf = (doc: Doc): AuthHint[] =>
+  Object.entries(doc.securitySchemes).map(([scheme, s]) => ({ scheme, ...s }));
+
+const selected = (doc: Doc, endpoint: Endpoint) =>
+  endpoint.operations === undefined
+    ? doc.operations
+    : doc.operations.filter((o) => endpoint.operations?.includes(o.name));
+
+const INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    body: { type: "object", description: "JSON request body, for operations that take one." },
+  },
+  additionalProperties: false,
+};
+
+const isObj = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+async function openSession(endpoint: Endpoint, args: ConnectorOpenArgs): Promise<ConnectorSession> {
+  const doc = await loadDoc(endpoint, args.signal);
+  const base = endpoint.baseUrl ?? doc.baseUrl ?? new URL(endpoint.specUrl).origin;
+  const ops = selected(doc, endpoint);
+  return {
+    listTools: async () =>
+      ops.map(
+        (o): ToolSpec => ({
+          name: o.name,
+          description: o.summary ?? `${o.method} ${o.path}`,
+          inputSchema: INPUT_SCHEMA,
+          ...(o.annotations !== undefined && {
+            annotations: Object.fromEntries(
+              Object.entries(o.annotations).filter(([, v]) => v !== undefined),
+            ) as NonNullable<ToolSpec["annotations"]>,
+          }),
+          connectorData: { method: o.method, path: o.path },
+        }),
+      ),
+    async callTool(name, input, signal, ctx) {
+      const data = ctx?.spec.connectorData;
+      const op = ops.find((o) => o.name === name);
+      const method = typeof data?.method === "string" ? data.method : op?.method;
+      const path = typeof data?.path === "string" ? data.path : op?.path;
+      if (method === undefined || path === undefined) {
+        throw new ToolError(`Unknown operation ${name}; check the tool name and retry.`);
+      }
+      const body = isObj(input) && isObj(input.body) ? JSON.stringify(input.body) : undefined;
+      const send = async (): Promise<Response> => {
+        const inj = await args.auth();
+        const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`);
+        for (const [k, v] of Object.entries(inj.query ?? {})) url.searchParams.set(k, v);
+        const headers = new Headers(inj.headers);
+        if (body !== undefined) headers.set("content-type", "application/json");
+        try {
+          return await fetch(url, {
+            method,
+            headers,
+            ...(body !== undefined && { body }),
+            signal: AbortSignal.any([signal, args.signal]),
+            redirect: "manual",
+          });
+        } catch (e) {
+          if (signal.aborted || args.signal.aborted) throw e;
+          throw new ToolError(UNREACHABLE_TEXT, { kind: "unavailable" });
+        }
+      };
+      let res = await send();
+      if (res.status === 401) {
+        await res.body?.cancel();
+        await args.onUnauthorized();
+        res = await send();
+        if (res.status === 401) {
+          await res.body?.cancel();
+          throw new ToolError(AUTH_FAILED_TEXT);
+        }
+      }
+      const text = await res.text();
+      if (res.status >= 500) {
+        throw new ToolError(
+          `The connector's server responded with HTTP ${res.status}; retry later.`,
+          {
+            kind: "unavailable",
+          },
+        );
+      }
+      if (res.status >= 300) {
+        return {
+          content: [{ type: "text", text: `HTTP ${res.status}: ${text}` }],
+          isError: true,
+        } satisfies ToolResult;
+      }
+      return { content: [{ type: "text", text }] } satisfies ToolResult;
+    },
+    async close() {},
+  };
+}
+
+async function inspect(endpoint: Endpoint, signal: AbortSignal): Promise<ConnectorInspection> {
+  const doc = await loadDoc(endpoint, signal);
+  return {
+    authHints: hintsOf(doc),
+    operations: doc.operations.map((o) => ({
+      id: o.name,
+      method: o.method,
+      path: o.path,
+      ...(o.summary !== undefined && { summary: o.summary }),
+    })),
+  };
+}
+
+/** Creates the fake OpenAPI connector (exported for unit tests that call it without a kernel). */
+export function createFakeOpenApiConnector(allowInsecureLoopback: boolean): Connector {
+  const schema = fakeOpenApiEndpointSchema(allowInsecureLoopback);
+  return {
+    kind: "openapi",
+    endpointSchema: schema,
+    open: (args) => openSession(schema.parse(args.endpoint), args),
+    inspect: ({ endpoint, signal }) => inspect(schema.parse(endpoint), signal),
+  };
+}
+
+export default defineExtension({
+  name: "fake-openapi",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [CONNECTOR_EXTENSION_POINT],
+  config: { deployment: DeploymentConfig },
+  setup(ctx) {
+    const { allowInsecureLoopback } = DeploymentConfig.parse(ctx.config ?? {});
+    ctx.provide(CONNECTOR_EXTENSION_POINT, createFakeOpenApiConnector(allowInsecureLoopback));
+  },
+});

package/fixtures/extensions/fake-storage-user/.capybara-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "name": "fake-storage-user",
+  "version": "0.1.0",
+  "publisher": "Capybara",
+  "description": "Test fake: an extension tool that writes through ctx.storage (needs an object-store@1 provider)"
+}

package/fixtures/extensions/fake-storage-user/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@capybara-hq/test-plugin-fake-storage-user",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Test fake: an extension tool that writes through ctx.storage (needs an object-store@1 provider)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
+    "zod": "^4.6.7"
+  }
+}

package/fixtures/extensions/fake-storage-user/src/index.ts

@@ -0,0 +1,58 @@
+import { defineExtension, ToolError, type ToolSpec } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+
+/**
+ * Test fake of an extension that uses `ctx.storage` (`permissions.storage`): tool `note`
+ * (model-visible `fake-storage-user__note`) writes the text to `notes/<conversationId>.txt`, which
+ * the kernel prefixes with `plugins/fake-storage-user/<orgId>/`, and returns the stored size; tool
+ * `read_note` returns it (or says there is none). Needs an `object-store@1` provider.
+ */
+
+const NoteInput = z.object({ text: z.string().max(10_000) });
+
+const NOTE: ToolSpec = {
+  name: "note",
+  description:
+    "Store a text note for the current conversation in object storage. Test fixture only.",
+  inputSchema: {
+    type: "object",
+    properties: { text: { type: "string", maxLength: 10_000, description: "The note text." } },
+    required: ["text"],
+    additionalProperties: false,
+  },
+};
+
+const READ_NOTE: ToolSpec = {
+  name: "read_note",
+  description: "Read the text note stored for the current conversation. Test fixture only.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  annotations: { readOnlyHint: true },
+};
+
+const keyOf = (conversationId: string) => `notes/${conversationId}.txt`;
+
+export default defineExtension({
+  name: "fake-storage-user",
+  version: "0.1.0",
+  sdk: "^0.1.0-rc.0",
+  provides: [],
+  permissions: { tools: ["note", "read_note"], storage: true },
+  setup(ctx) {
+    ctx.tools.register(NOTE, async (input, tctx) => {
+      const parsed = NoteInput.safeParse(input);
+      if (!parsed.success) throw new ToolError("Invalid note: pass { text } with a string text.");
+      const head = await ctx.storage.put(
+        tctx.orgId,
+        keyOf(tctx.conversationId),
+        new TextEncoder().encode(parsed.data.text),
+        { contentType: "text/plain" },
+      );
+      return { content: [{ type: "text", text: `Stored the note (${head.size} bytes).` }] };
+    });
+    ctx.tools.register(READ_NOTE, async (_input, tctx) => {
+      const got = await ctx.storage.get(tctx.orgId, keyOf(tctx.conversationId));
+      const text = got === null ? "There is no note yet." : await new Response(got.body).text();
+      return { content: [{ type: "text", text }] };
+    });
+  },
+});