@jitsusama/agentic-harness.core 0.1.0

package/dist/google/apis/sheets.js

@@ -0,0 +1,54 @@
+/**
+ * Google Sheets API client.
+ */
+import { google } from "googleapis";
+/**
+ * Get spreadsheet content.
+ */
+export async function getSheetContent(auth, spreadsheetId) {
+    const sheets = google.sheets({ version: "v4", auth });
+    const spreadsheet = await sheets.spreadsheets.get({
+        spreadsheetId,
+    });
+    const title = spreadsheet.data.properties?.title || "Untitled";
+    const sheetNames = spreadsheet.data.sheets?.map((s) => s.properties?.title || "") || [];
+    const sheetData = {
+        title,
+        sheets: [],
+    };
+    // We get the data from each sheet.
+    for (const sheetName of sheetNames) {
+        if (!sheetName)
+            continue;
+        // We escape single quotes in the sheet name by doubling them.
+        const escapedName = sheetName.replace(/'/g, "''");
+        try {
+            const result = await sheets.spreadsheets.values.get({
+                spreadsheetId,
+                range: `'${escapedName}'`,
+            });
+            const rows = (result.data.values || []);
+            sheetData.sheets.push({
+                name: sheetName,
+                rows,
+            });
+        }
+        catch (error) {
+            // If a sheet fails, we continue with the others.
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            // This is a special case for connected sheets or unsupported sheet types.
+            let friendlyMessage = `Error loading sheet: ${errorMsg}`;
+            if (errorMsg.includes("Invalid range")) {
+                friendlyMessage =
+                    `This sheet ("${sheetName}") cannot be read via API. ` +
+                        "It may be a Connected Sheet or other special sheet type that " +
+                        "doesn't support range queries.";
+            }
+            sheetData.sheets.push({
+                name: sheetName,
+                rows: [[friendlyMessage]],
+            });
+        }
+    }
+    return sheetData;
+}

package/dist/google/apis/slides.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Google Slides API client.
+ */
+import type { OAuth2Client } from "google-auth-library";
+/** Extracted content from a Google Slides presentation. */
+export interface SlideData {
+    title: string;
+    slides: Array<{
+        number: number;
+        text: string;
+    }>;
+}
+/**
+ * Get presentation content.
+ */
+export declare function getSlideContent(auth: OAuth2Client, presentationId: string): Promise<SlideData>;

package/dist/google/apis/slides.js

@@ -0,0 +1,40 @@
+/**
+ * Google Slides API client.
+ */
+import { google } from "googleapis";
+/**
+ * Get presentation content.
+ */
+export async function getSlideContent(auth, presentationId) {
+    const slides = google.slides({ version: "v1", auth });
+    const presentation = await slides.presentations.get({
+        presentationId,
+    });
+    const title = presentation.data.title || "Untitled";
+    const slideData = {
+        title,
+        slides: [],
+    };
+    for (let i = 0; i < (presentation.data.slides || []).length; i++) {
+        const slide = presentation.data.slides?.[i];
+        if (!slide)
+            continue;
+        let text = "";
+        for (const pageElement of slide.pageElements || []) {
+            const shape = pageElement.shape;
+            if (!shape?.text)
+                continue;
+            for (const textElement of shape.text.textElements || []) {
+                const textRun = textElement.textRun;
+                if (textRun?.content) {
+                    text += textRun.content;
+                }
+            }
+        }
+        slideData.slides.push({
+            number: i + 1,
+            text: text.trim(),
+        });
+    }
+    return slideData;
+}

package/dist/google/auth/browser.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cross-platform URL opener. Launches the system default browser.
+ */
+/** Open a URL in the user's default browser. */
+export declare function openInBrowser(url: string): void;

package/dist/google/auth/browser.js

@@ -0,0 +1,27 @@
+/**
+ * Cross-platform URL opener. Launches the system default browser.
+ */
+import { execFile } from "node:child_process";
+/** Open a URL in the user's default browser. */
+export function openInBrowser(url) {
+    const platform = process.platform;
+    if (platform === "darwin") {
+        execFile("open", [url], ignoreErrors);
+    }
+    else if (platform === "win32") {
+        execFile("cmd", ["/c", "start", url], ignoreErrors);
+    }
+    else {
+        // Linux and other Unix-like systems
+        execFile("xdg-open", [url], ignoreErrors);
+    }
+}
+/** Silently ignore errors: the URL is also displayed as a fallback. */
+function ignoreErrors(error) {
+    // Browser launch is best-effort. If it fails (e.g. headless
+    // server, missing xdg-open), the user can still copy the URL
+    // shown in the terminal.
+    if (error) {
+        // Intentionally ignored: URL is displayed as fallback
+    }
+}

package/dist/google/auth/credentials.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Account and token management: storing, retrieving and
+ * managing Google account configurations and their OAuth
+ * tokens.
+ */
+import type { Credentials } from "google-auth-library";
+import type { GoogleAccount } from "../types.js";
+export type { OAuthAppCredentials } from "./oauth-app.js";
+export { getOAuthApp, hasOAuthApp, storeOAuthApp, } from "./oauth-app.js";
+/** Store credentials for an account. */
+export declare function storeCredentials(account: string, credentials: Credentials): void;
+/** Retrieve credentials for an account. */
+export declare function getCredentials(account: string): Credentials | null;
+/** List all configured accounts. */
+export declare function listAccounts(): GoogleAccount[];
+/** Add or update an account. */
+export declare function saveAccount(account: GoogleAccount): void;
+/** Get the default account. */
+export declare function getDefaultAccount(): GoogleAccount | null;
+/** Set the default account by name. */
+export declare function setDefaultAccount(accountName: string): void;
+/**
+ * Clear all Google Workspace configuration (OAuth app,
+ * accounts, tokens). Used for resetting to a fresh state.
+ */
+export declare function clearAllConfig(): void;

package/dist/google/auth/credentials.js

@@ -0,0 +1,69 @@
+/**
+ * Account and token management: storing, retrieving and
+ * managing Google account configurations and their OAuth
+ * tokens.
+ */
+import { readFile, writeFile } from "./store.js";
+export { getOAuthApp, hasOAuthApp, storeOAuthApp, } from "./oauth-app.js";
+/** Store credentials for an account. */
+export function storeCredentials(account, credentials) {
+    const data = readFile();
+    data.tokens[account] = {
+        access_token: credentials.access_token || "",
+        refresh_token: credentials.refresh_token || "",
+        expiry_date: credentials.expiry_date || 0,
+        token_type: credentials.token_type || "Bearer",
+        scope: credentials.scope || "",
+    };
+    writeFile(data);
+}
+/** Retrieve credentials for an account. */
+export function getCredentials(account) {
+    const data = readFile();
+    const entry = data.tokens[account];
+    if (!entry)
+        return null;
+    return {
+        access_token: entry.access_token,
+        refresh_token: entry.refresh_token,
+        expiry_date: entry.expiry_date,
+        token_type: entry.token_type,
+        scope: entry.scope,
+    };
+}
+/** List all configured accounts. */
+export function listAccounts() {
+    return readFile().accounts;
+}
+/** Add or update an account. */
+export function saveAccount(account) {
+    const data = readFile();
+    const existing = data.accounts.findIndex((a) => a.name === account.name);
+    if (existing >= 0) {
+        data.accounts[existing] = account;
+    }
+    else {
+        data.accounts.push(account);
+    }
+    writeFile(data);
+}
+/** Get the default account. */
+export function getDefaultAccount() {
+    const accounts = listAccounts();
+    return accounts.find((a) => a.isDefault) || accounts[0] || null;
+}
+/** Set the default account by name. */
+export function setDefaultAccount(accountName) {
+    const data = readFile();
+    for (const account of data.accounts) {
+        account.isDefault = account.name === accountName;
+    }
+    writeFile(data);
+}
+/**
+ * Clear all Google Workspace configuration (OAuth app,
+ * accounts, tokens). Used for resetting to a fresh state.
+ */
+export function clearAllConfig() {
+    writeFile({ oauthApp: null, accounts: [], tokens: {} });
+}

package/dist/google/auth/errors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Formatting a Google Workspace auth failure for a tool result.
+ *
+ * Split out of the interactive auth orchestration (which needs a
+ * host's UI to run the device/web flow and stays adapter-local)
+ * because this part is pure: an error in, a message out. The
+ * messages are exported too, since the adapter-local orchestration
+ * throws them verbatim to reach this formatter.
+ */
+export declare const AUTH_MESSAGES: {
+    cancelled: string;
+    setupCancelled: string;
+};
+/** Format an auth error for tool results. */
+export declare function formatAuthError(error: unknown): string;

package/dist/google/auth/errors.js

@@ -0,0 +1,26 @@
+/**
+ * Formatting a Google Workspace auth failure for a tool result.
+ *
+ * Split out of the interactive auth orchestration (which needs a
+ * host's UI to run the device/web flow and stays adapter-local)
+ * because this part is pure: an error in, a message out. The
+ * messages are exported too, since the adapter-local orchestration
+ * throws them verbatim to reach this formatter.
+ */
+export const AUTH_MESSAGES = {
+    cancelled: "⚠️ Authentication required but was cancelled.\n\n" +
+        "Run /google-auth to authenticate with your Google account.",
+    setupCancelled: "⚠️ OAuth credentials setup required but was cancelled.\n\n" +
+        "Run /google-setup to configure Google Workspace access.",
+};
+/** Format an auth error for tool results. */
+export function formatAuthError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("cancelled")) {
+        return AUTH_MESSAGES.cancelled;
+    }
+    if (message.includes("setup required")) {
+        return AUTH_MESSAGES.setupCancelled;
+    }
+    return `Google Workspace API error: ${message}`;
+}

package/dist/google/auth/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Google Workspace authentication: credential state and error
+ * formatting.
+ *
+ * `ensureAuthenticated` itself, the interactive orchestration that
+ * runs the setup wizard and/or device/web OAuth flow, needs a
+ * host's UI and stays adapter-local; everything it is built from
+ * (credential storage, the OAuth client, the callback server, the
+ * browser opener, error formatting) lives here.
+ */
+export { clearAllConfig, getCredentials, getDefaultAccount, getOAuthApp, hasOAuthApp, listAccounts, type OAuthAppCredentials, saveAccount, setDefaultAccount, storeCredentials, storeOAuthApp, } from "./credentials.js";
+export { AUTH_MESSAGES, formatAuthError } from "./errors.js";

package/dist/google/auth/index.js

@@ -0,0 +1,12 @@
+/**
+ * Google Workspace authentication: credential state and error
+ * formatting.
+ *
+ * `ensureAuthenticated` itself, the interactive orchestration that
+ * runs the setup wizard and/or device/web OAuth flow, needs a
+ * host's UI and stays adapter-local; everything it is built from
+ * (credential storage, the OAuth client, the callback server, the
+ * browser opener, error formatting) lives here.
+ */
+export { clearAllConfig, getCredentials, getDefaultAccount, getOAuthApp, hasOAuthApp, listAccounts, saveAccount, setDefaultAccount, storeCredentials, storeOAuthApp, } from "./credentials.js";
+export { AUTH_MESSAGES, formatAuthError } from "./errors.js";

package/dist/google/auth/oauth-app.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OAuth app credential management: storing and retrieving
+ * the client ID and secret used for Google API authentication.
+ */
+/** OAuth app credentials (client ID + secret). */
+export interface OAuthAppCredentials {
+    readonly clientId: string;
+    readonly clientSecret: string;
+}
+/** Store OAuth app credentials. */
+export declare function storeOAuthApp(credentials: OAuthAppCredentials): void;
+/** Retrieve OAuth app credentials. */
+export declare function getOAuthApp(): OAuthAppCredentials | null;
+/** Check if OAuth app credentials are configured. */
+export declare function hasOAuthApp(): boolean;

package/dist/google/auth/oauth-app.js

@@ -0,0 +1,20 @@
+/**
+ * OAuth app credential management: storing and retrieving
+ * the client ID and secret used for Google API authentication.
+ */
+import { readFile, writeFile } from "./store.js";
+/** Store OAuth app credentials. */
+export function storeOAuthApp(credentials) {
+    const data = readFile();
+    data.oauthApp = credentials;
+    writeFile(data);
+}
+/** Retrieve OAuth app credentials. */
+export function getOAuthApp() {
+    return readFile().oauthApp ?? null;
+}
+/** Check if OAuth app credentials are configured. */
+export function hasOAuthApp() {
+    const creds = getOAuthApp();
+    return !!(creds?.clientId && creds?.clientSecret);
+}

package/dist/google/auth/oauth.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OAuth2 authentication for Google Workspace APIs.
+ * Uses OAuth 2.0 Device Flow for universal compatibility.
+ */
+import type { Credentials } from "google-auth-library";
+import { OAuth2Client } from "google-auth-library";
+/** OAuth2 scopes required for the extension. */
+export declare const SCOPES: string[];
+/** OAuth2 client configuration. */
+export interface OAuth2Config {
+    clientId: string;
+    clientSecret: string;
+}
+/** Device flow response from Google. */
+export interface DeviceFlowResponse {
+    device_code: string;
+    user_code: string;
+    verification_url: string;
+    expires_in: number;
+    interval: number;
+}
+/**
+ * Create an OAuth2 client for device flow.
+ */
+export declare function createOAuth2Client(config: OAuth2Config): OAuth2Client;
+/**
+ * Initiate device flow by requesting a device code.
+ */
+export declare function initiateDeviceFlow(config: OAuth2Config): Promise<DeviceFlowResponse>;
+/**
+ * Poll for device flow authorization completion.
+ * Returns credentials when user completes authorization.
+ */
+export declare function pollForDeviceAuthorization(config: OAuth2Config, deviceCode: string, interval: number, signal?: AbortSignal): Promise<Credentials>;
+/**
+ * Set credentials on an OAuth2 client.
+ */
+export declare function setCredentials(client: OAuth2Client, credentials: Credentials): void;
+/**
+ * Refresh access token if expired.
+ */
+export declare function refreshTokenIfNeeded(client: OAuth2Client): Promise<Credentials | null>;
+/**
+ * Extract the current token credentials from an OAuth2 client.
+ */
+export declare function extractTokens(client: OAuth2Client): Credentials;

package/dist/google/auth/oauth.js

@@ -0,0 +1,146 @@
+/**
+ * OAuth2 authentication for Google Workspace APIs.
+ * Uses OAuth 2.0 Device Flow for universal compatibility.
+ */
+import { OAuth2Client } from "google-auth-library";
+/** OAuth2 scopes required for the extension. */
+export const SCOPES = [
+    // Gmail - read and modify (send, delete, archive)
+    "https://www.googleapis.com/auth/gmail.modify",
+    // Calendar - full access
+    "https://www.googleapis.com/auth/calendar",
+    // Drive - read-only
+    "https://www.googleapis.com/auth/drive.readonly",
+    // Docs - read-only
+    "https://www.googleapis.com/auth/documents.readonly",
+    // Sheets - read-only
+    "https://www.googleapis.com/auth/spreadsheets.readonly",
+    // Slides - read-only
+    "https://www.googleapis.com/auth/presentations.readonly",
+];
+/**
+ * Create an OAuth2 client for device flow.
+ */
+export function createOAuth2Client(config) {
+    return new OAuth2Client(config.clientId, config.clientSecret);
+}
+/**
+ * Initiate device flow by requesting a device code.
+ */
+export async function initiateDeviceFlow(config) {
+    const response = await fetch("https://oauth2.googleapis.com/device/code", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            client_id: config.clientId,
+            scope: SCOPES.join(" "),
+        }),
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        // We check for an invalid client type error (wrong OAuth app type).
+        if (error.includes("invalid_client")) {
+            throw new Error("Invalid OAuth client type. Your OAuth credentials must be created as " +
+                "'TVs and Limited Input devices' (NOT Desktop app).\n\n" +
+                "Please:\n" +
+                "1. Go to https://console.cloud.google.com/apis/credentials\n" +
+                "2. Delete your existing OAuth client\n" +
+                "3. Create new credentials with type 'TVs and Limited Input devices'\n" +
+                "4. Run /google-setup again with the new credentials");
+        }
+        throw new Error(`Device flow initiation failed: ${error}`);
+    }
+    return (await response.json());
+}
+/**
+ * Poll for device flow authorization completion.
+ * Returns credentials when user completes authorization.
+ */
+export async function pollForDeviceAuthorization(config, deviceCode, interval, signal) {
+    const pollInterval = (interval || 5) * 1000; // Convert to milliseconds
+    while (!signal?.aborted) {
+        // We wait before polling.
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        if (signal?.aborted) {
+            throw new Error("Authorization cancelled");
+        }
+        try {
+            const response = await fetch("https://oauth2.googleapis.com/token", {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: new URLSearchParams({
+                    client_id: config.clientId,
+                    client_secret: config.clientSecret,
+                    device_code: deviceCode,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.json();
+                // These errors mean we should keep polling.
+                if (error.error === "authorization_pending" ||
+                    error.error === "slow_down") {
+                    continue;
+                }
+                // These errors mean authorization failed.
+                if (error.error === "expired_token") {
+                    throw new Error("Authorization code expired. Please try again.");
+                }
+                if (error.error === "access_denied") {
+                    throw new Error("Authorization denied by user.");
+                }
+                throw new Error(`Token exchange failed: ${error.error_description || error.error}`);
+            }
+            // The exchange succeeded, so we convert the response to our credentials format.
+            const tokenResponse = (await response.json());
+            return {
+                access_token: tokenResponse.access_token,
+                refresh_token: tokenResponse.refresh_token,
+                expiry_date: Date.now() + tokenResponse.expires_in * 1000,
+                token_type: tokenResponse.token_type,
+                scope: tokenResponse.scope,
+            };
+        }
+        catch (error) {
+            // Our own authorization errors should bubble up rather than being retried.
+            if (error instanceof Error && error.message.includes("Authorization")) {
+                throw error;
+            }
+        }
+    }
+    throw new Error("Authorization cancelled");
+}
+/**
+ * Set credentials on an OAuth2 client.
+ */
+export function setCredentials(client, credentials) {
+    client.setCredentials(credentials);
+}
+/**
+ * Refresh access token if expired.
+ */
+export async function refreshTokenIfNeeded(client) {
+    const credentials = client.credentials;
+    // We refresh proactively when the token is within 5 minutes of expiry.
+    if (credentials.expiry_date) {
+        const expiryTime = credentials.expiry_date;
+        const now = Date.now();
+        const fiveMinutes = 5 * 60 * 1000;
+        if (expiryTime - now < fiveMinutes) {
+            const { credentials: newCredentials } = await client.refreshAccessToken();
+            client.setCredentials(newCredentials);
+            return newCredentials;
+        }
+    }
+    return null;
+}
+/**
+ * Extract the current token credentials from an OAuth2 client.
+ */
+export function extractTokens(client) {
+    return client.credentials;
+}

package/dist/google/auth/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Local HTTP server for OAuth2 callback handling.
+ */
+/** Result from the local OAuth2 callback server: either an auth code or an error. */
+export interface OAuthCallbackResult {
+    code?: string;
+    error?: string;
+}
+/**
+ * Start a local server to handle the OAuth callback.
+ * Returns a promise that resolves when the callback is received.
+ */
+export declare function waitForOAuthCallback(port?: number): Promise<OAuthCallbackResult>;

package/dist/google/auth/server.js

@@ -0,0 +1,70 @@
+/**
+ * Local HTTP server for OAuth2 callback handling.
+ */
+import * as http from "node:http";
+/** Timeout before the OAuth callback server gives up (5 minutes). */
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;
+const PAGE_STYLES = `
+body {
+  font-family: system-ui, -apple-system, sans-serif;
+  padding: 3rem 1rem;
+  text-align: center;
+  color: #1a1a1a;
+  background: #fafafa;
+}
+@media (prefers-color-scheme: dark) {
+  body { color: #e0e0e0; background: #1a1a1a; }
+}`;
+const SUCCESS_PAGE = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Authentication Successful</title>
+  <style>${PAGE_STYLES}</style>
+</head>
+<body>
+  <h1>✓ Authentication Successful</h1>
+  <p>You can close this tab and return to Pi.</p>
+  <script>setTimeout(() => window.close(), 1500)</script>
+</body>
+</html>`;
+function errorPage(error) {
+    return `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Authentication Failed</title>
+  <style>${PAGE_STYLES}</style>
+</head>
+<body>
+  <h1>✗ Authentication Failed</h1>
+  <p>Error: ${error || "Unknown error"}</p>
+  <p>Please try again.</p>
+</body>
+</html>`;
+}
+/**
+ * Start a local server to handle the OAuth callback.
+ * Returns a promise that resolves when the callback is received.
+ */
+export async function waitForOAuthCallback(port = 8765) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url || "", `http://localhost:${port}`);
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end(code ? SUCCESS_PAGE : errorPage(error || ""));
+            server.close();
+            resolve({ code: code || undefined, error: error || undefined });
+        });
+        server.on("error", (err) => {
+            reject(err);
+        });
+        server.listen(port, "localhost");
+        setTimeout(() => {
+            server.close();
+            reject(new Error("OAuth callback timeout after 5 minutes"));
+        }, CALLBACK_TIMEOUT_MS);
+    });
+}

package/dist/google/auth/setup-instructions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Validation helpers and error messages used during the OAuth
+ * credential setup flow.
+ */
+/** Error messages for invalid credentials. */
+export declare const ERRORS: {
+    invalidClientId: string;
+    missingClientSecret: string;
+};
+/** Validate OAuth Client ID format. */
+export declare function isValidClientId(clientId: string | null): boolean;
+/**
+ * Validate OAuth Client Secret format.
+ * Accepts any non-empty string (format varies by OAuth client type).
+ */
+export declare function isValidClientSecret(clientSecret: string | null): boolean;

package/dist/google/auth/setup-instructions.js

@@ -0,0 +1,24 @@
+/**
+ * Validation helpers and error messages used during the OAuth
+ * credential setup flow.
+ */
+/** Error messages for invalid credentials. */
+export const ERRORS = {
+    invalidClientId: "Invalid Client ID. It should end with .apps.googleusercontent.com",
+    missingClientSecret: "Client Secret is required.",
+};
+/** Validate OAuth Client ID format. */
+export function isValidClientId(clientId) {
+    if (!clientId)
+        return false;
+    return clientId.trim().endsWith(".apps.googleusercontent.com");
+}
+/**
+ * Validate OAuth Client Secret format.
+ * Accepts any non-empty string (format varies by OAuth client type).
+ */
+export function isValidClientSecret(clientSecret) {
+    if (!clientSecret)
+        return false;
+    return clientSecret.trim().length > 0;
+}