@devosurf/tesser-connectors 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@devosurf/tesser-connectors",
+  "version": "0.1.0-alpha.0",
+  "description": "Tesser connector library — typed integrations consumed as ctx.connections.<name>.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./catalog": "./catalog/index.ts",
+    "./*": "./*/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@devosurf/tesser-sdk": "0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@devosurf/tesser-testing": "^0.1.0-alpha.0"
+  },
+  "files": [
+    "index.ts",
+    "catalog/index.ts",
+    "providers/*.ts",
+    "*/index.ts",
+    "manifest.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/pi/index.ts

@@ -0,0 +1,230 @@
+// Pi Harness adapter (ADR-0019): one-shot, non-interactive, broker-authed, and run
+// with isolated Pi config/session dirs so host Pi login state is never used.
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { apiKey, customAuth, defineConnector } from "@devosurf/tesser-sdk/connector";
+import type { HarnessDef, HarnessRunRequest, HarnessRunResult, Serializable } from "@devosurf/tesser-sdk";
+import { decodeJournal, encodeJournal, parseDuration } from "@devosurf/tesser-sdk/internal";
+
+export default defineConnector<Record<string, never>>({
+  id: "pi",
+  describe: "Pi one-shot Harness runner",
+  auth: {
+    anthropicApiKey: apiKey({ name: "ANTHROPIC_API_KEY", describe: "Anthropic API key for Pi" }),
+    anthropicOAuth: customAuth({
+      describe: "Anthropic OAuth token for Pi",
+      fields: ["oauth_token"],
+      sign: () => {},
+    }),
+  },
+  actions: {},
+  harnessProvider: {
+    adapter: "pi-print-json",
+    run: async (ctx, request, def) => runPi(ctx.auth.mode ?? "anthropicApiKey", ctx.auth.fields, request, def),
+  },
+});
+
+async function runPi(
+  authMode: string,
+  fields: Readonly<Record<string, string>>,
+  request: HarnessRunRequest<unknown>,
+  def: HarnessDef,
+): Promise<HarnessRunResult<unknown>> {
+  const timeoutMs = parseDuration(request.timeout ?? def.timeout ?? "10m", "pi harness timeout");
+  const maxOutputBytes = request.maxOutputBytes ?? def.maxOutputBytes ?? 2_000_000;
+  const home = await mkdtemp(join(tmpdir(), "tesser-pi-home-"));
+  const agentDir = await mkdtemp(join(tmpdir(), "tesser-pi-agent-"));
+  const sessionDir = await mkdtemp(join(tmpdir(), "tesser-pi-sessions-"));
+  const cwd = await mkdtemp(join(tmpdir(), "tesser-pi-cwd-"));
+  try {
+    await writeFile(join(cwd, "input.json"), JSON.stringify(request.input ?? {}, null, 2));
+    const model = process.env["TESSER_PI_MODEL"] ?? "anthropic/haiku";
+    const args = [
+      "--print",
+      "--mode",
+      "json",
+      "--model",
+      model,
+      "--no-session",
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-themes",
+      "--no-context-files",
+      ...(def.permissions === "read-only" ? ["--tools", "read,grep,find,ls"] : []),
+      request.prompt + "\n\nReturn JSON only matching the requested schema. Input JSON is in ./input.json and also below:\n" + JSON.stringify(request.input ?? {}),
+    ];
+    const token = authMode === "anthropicOAuth" ? fields["oauth_token"] : fields["api_key"];
+    if (!token) throw new Error(`pi ${authMode} credential is empty`);
+    const proc = await runProcess(process.env["TESSER_PI_BIN"] ?? "pi", args, {
+      cwd,
+      timeoutMs,
+      maxOutputBytes,
+      env: {
+        PATH: process.env["PATH"] ?? "/usr/bin:/bin:/opt/homebrew/bin:/usr/local/bin",
+        HOME: home,
+        PI_CODING_AGENT_DIR: agentDir,
+        PI_CODING_AGENT_SESSION_DIR: sessionDir,
+        PI_OFFLINE: "1",
+        NO_COLOR: "1",
+        ...(authMode === "anthropicOAuth" ? { ANTHROPIC_OAUTH_TOKEN: token } : { ANTHROPIC_API_KEY: token }),
+      },
+    });
+    const output = parsePiOutput(proc.stdout);
+    return {
+      output: toSerializable(output),
+      status: proc.exitCode === 0 ? "completed" : "failed",
+      exitCode: proc.exitCode,
+      artifacts: [
+        { name: "stdout.json", kind: "transcript", bytes: Buffer.byteLength(proc.stdout), content: clip(proc.stdout, 120_000) },
+        ...(proc.stderr.length > 0
+          ? [{ name: "stderr.log", kind: "log" as const, bytes: Buffer.byteLength(proc.stderr), content: clip(proc.stderr, 80_000) }]
+          : []),
+      ],
+      transcript: clip(proc.stdout, 120_000),
+      adapter: "pi-print-json",
+      raw: toSerializable({ exitCode: proc.exitCode }),
+    };
+  } finally {
+    await rm(home, { recursive: true, force: true });
+    await rm(agentDir, { recursive: true, force: true });
+    await rm(sessionDir, { recursive: true, force: true });
+    await rm(cwd, { recursive: true, force: true });
+  }
+}
+
+function runProcess(
+  command: string,
+  args: string[],
+  opts: { cwd: string; env: Record<string, string>; timeoutMs: number; maxOutputBytes: number },
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd: opts.cwd, env: opts.env, stdio: ["ignore", "pipe", "pipe"] });
+    const chunks: Buffer[] = [];
+    const errChunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    const fail = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      child.kill("SIGTERM");
+      reject(err);
+    };
+    const timer = setTimeout(() => fail(new Error(`pi harness timed out after ${opts.timeoutMs}ms`)), opts.timeoutMs);
+    timer.unref?.();
+    const collect = (buf: Buffer, target: Buffer[]) => {
+      size += buf.length;
+      if (size > opts.maxOutputBytes) {
+        fail(new Error(`pi harness exceeded maxOutputBytes (${opts.maxOutputBytes})`));
+        return;
+      }
+      target.push(buf);
+    };
+    child.stdout.on("data", (b: Buffer) => collect(b, chunks));
+    child.stderr.on("data", (b: Buffer) => collect(b, errChunks));
+    child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ exitCode: code ?? 1, stdout: Buffer.concat(chunks).toString("utf8"), stderr: Buffer.concat(errChunks).toString("utf8") });
+    });
+  });
+}
+
+function parsePiOutput(stdout: string): unknown {
+  const text = stdout.trim();
+  if (!text) return {};
+  const parsed = tryJson(text);
+  if (parsed !== undefined) return normalizeOutputValue(unwrapKnownOutput(parsed));
+  const streamed = parsePiJsonLines(text);
+  if (streamed !== undefined) return streamed;
+  return parseJsonishText(text) ?? { text };
+}
+
+function parsePiJsonLines(text: string): unknown | undefined {
+  const events = text
+    .split(/\r?\n/)
+    .map((l) => tryJson(l.trim()))
+    .filter((v): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v));
+  for (let i = events.length - 1; i >= 0; i -= 1) {
+    const event = events[i]!;
+    const direct = unwrapKnownOutput(event);
+    if (direct !== event) return normalizeOutputValue(direct);
+    if (event["type"] === "agent_end" && Array.isArray(event["messages"])) {
+      const textValue = lastAssistantText(event["messages"]);
+      if (textValue !== undefined) return normalizeOutputValue(textValue);
+    }
+    if (typeof event["message"] === "object" && event["message"] !== null) {
+      const textValue = messageText(event["message"] as Record<string, unknown>);
+      if (textValue !== undefined) return normalizeOutputValue(textValue);
+    }
+  }
+  return undefined;
+}
+
+function lastAssistantText(messages: unknown[]): string | undefined {
+  for (let i = messages.length - 1; i >= 0; i -= 1) {
+    const msg = messages[i];
+    if (typeof msg !== "object" || msg === null || Array.isArray(msg)) continue;
+    const obj = msg as Record<string, unknown>;
+    if (obj["role"] !== "assistant") continue;
+    const text = messageText(obj);
+    if (text !== undefined) return text;
+  }
+  return undefined;
+}
+
+function messageText(message: Record<string, unknown>): string | undefined {
+  const content = message["content"];
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return undefined;
+  const texts = content
+    .filter((part): part is Record<string, unknown> => typeof part === "object" && part !== null && !Array.isArray(part))
+    .filter((part) => part["type"] === "text" && typeof part["text"] === "string")
+    .map((part) => part["text"] as string);
+  return texts.at(-1);
+}
+
+function normalizeOutputValue(value: unknown): unknown {
+  if (typeof value === "string") return parseJsonishText(value) ?? { text: value };
+  return value;
+}
+
+function unwrapKnownOutput(value: unknown): unknown {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+  const obj = value as Record<string, unknown>;
+  for (const key of ["structured_output", "output", "result", "message", "text", "content"]) {
+    if (obj[key] !== undefined) return obj[key];
+  }
+  return value;
+}
+
+function parseJsonishText(text: string): unknown | undefined {
+  const trimmed = text.trim();
+  return tryJson(trimmed) ?? tryJson(trimmed.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, ""));
+}
+
+function tryJson(text: string): unknown | undefined {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function toSerializable(value: unknown): Serializable {
+  return decodeJournal(encodeJournal(value)) as Serializable;
+}
+
+function clip(text: string, max: number): string {
+  return text.length <= max ? text : text.slice(0, max - 3) + "...";
+}

package/providers/anthropic.ts

@@ -0,0 +1,8 @@
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+export const anthropicProvider: ProviderFacts = {
+  id: "anthropic",
+  displayName: "Anthropic",
+  baseUrl: "https://api.anthropic.com",
+  docsUrl: "https://docs.anthropic.com",
+};

package/providers/github.ts

@@ -0,0 +1,20 @@
+// Provider facts: public OAuth/API knowledge we own (ADR-0004/0012). Declared here,
+// referenced by connectors, assembled into the Catalog by codegen — never hand-edit
+// the generated catalog.
+
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+export const githubProvider: ProviderFacts = {
+  id: "github",
+  displayName: "GitHub",
+  baseUrl: "https://api.github.com",
+  docsUrl: "https://docs.github.com/rest",
+  oauth2: {
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    clientAuth: "body",
+    scopeSeparator: " ",
+    // GitHub OAuth apps accept but do not enforce PKCE; sending it is harmless.
+    pkce: true,
+  },
+};

package/providers/google.ts

@@ -0,0 +1,18 @@
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+// One Provider backs several Connectors (gmail, google-calendar) — the unit an OAuth
+// app is registered against (CONTEXT.md "Provider").
+export const googleProvider: ProviderFacts = {
+  id: "google",
+  displayName: "Google",
+  docsUrl: "https://developers.google.com/identity/protocols/oauth2",
+  oauth2: {
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    clientAuth: "body",
+    scopeSeparator: " ",
+    pkce: true,
+    // Without these, Google never issues a refresh token (the classic quirk).
+    extraAuthorizeParams: { access_type: "offline", prompt: "consent" },
+  },
+};

package/providers/resend.ts

@@ -0,0 +1,8 @@
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+export const resendProvider: ProviderFacts = {
+  id: "resend",
+  displayName: "Resend",
+  baseUrl: "https://api.resend.com",
+  docsUrl: "https://resend.com/docs",
+};

package/providers/slack.ts

@@ -0,0 +1,16 @@
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+export const slackProvider: ProviderFacts = {
+  id: "slack",
+  displayName: "Slack",
+  baseUrl: "https://slack.com/api",
+  docsUrl: "https://docs.slack.dev",
+  oauth2: {
+    authorizeUrl: "https://slack.com/oauth/v2/authorize",
+    tokenUrl: "https://slack.com/api/oauth.v2.access",
+    clientAuth: "body",
+    // Slack separates scopes with commas, not spaces.
+    scopeSeparator: ",",
+    pkce: false,
+  },
+};

package/resend/index.ts

@@ -0,0 +1,51 @@
+// Resend connector — the P0 email path, and the exemplar of declared provider
+// idempotency: emails.send is a WRITE that derives retry-safety from the
+// Idempotency-Key header (ADR-0012).
+
+import { z } from "zod";
+import { action, apiKey, defineConnector } from "@devosurf/tesser-sdk/connector";
+import { resendProvider } from "../providers/resend.js";
+
+export default defineConnector({
+  id: "resend",
+  describe: "Transactional email via Resend",
+  provider: resendProvider,
+  auth: apiKey({ prefix: "Bearer ", describe: "Resend API key (re_…)" }),
+  idempotencyHeader: "Idempotency-Key",
+  samples: {
+    "emails.send": { id: "9f3c1a2b-0000-4000-8000-000000000000" },
+  },
+  actions: {
+    emails: {
+      send: action({
+        describe: "Send an email",
+        input: z.object({
+          from: z.string().min(3),
+          to: z.union([z.string(), z.array(z.string()).min(1)]),
+          subject: z.string().min(1),
+          html: z.string().optional(),
+          text: z.string().optional(),
+          replyTo: z.string().optional(),
+        }),
+        output: z.object({ id: z.string() }),
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post(
+            "/emails",
+            {
+              from: i.from,
+              to: Array.isArray(i.to) ? i.to : [i.to],
+              subject: i.subject,
+              ...(i.html !== undefined ? { html: i.html } : {}),
+              ...(i.text !== undefined ? { text: i.text } : {}),
+              ...(i.replyTo !== undefined ? { reply_to: i.replyTo } : {}),
+            },
+            ctx.idempotencyKey !== undefined
+              ? { headers: { "Idempotency-Key": ctx.idempotencyKey } }
+              : {},
+          )) as { id: string };
+          return { id: res.id };
+        },
+      }),
+    },
+  },
+});