@todoist/doistbot-cli 0.0.0-stage → 1.0.16

package/sandbox/dist/core/pii-scrubber.js

@@ -0,0 +1,31 @@
+import { Redactor } from '@redactpii/node';
+const redactor = new Redactor();
+/**
+ * Redact PII (emails, phone numbers, names, credit cards, SSNs) from text.
+ * Preserves numeric user IDs, service names, error messages, and code references.
+ */
+export function scrubPii(text) {
+    if (!text)
+        return text;
+    return redactor.redact(text);
+}
+/**
+ * Deep-scrub PII from a JSON-serializable object.
+ * Walks strings in objects/arrays recursively.
+ */
+export function scrubPiiFromObject(obj) {
+    if (typeof obj === 'string') {
+        return scrubPii(obj);
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => scrubPiiFromObject(item));
+    }
+    if (obj !== null && typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = scrubPiiFromObject(value);
+        }
+        return result;
+    }
+    return obj;
+}

package/sandbox/dist/core/prompt-template.js

@@ -0,0 +1,63 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from './logging.js';
+const promptCache = new Map();
+const resolveCache = new Map();
+/** Swap the `dist` directory nearest to the file (not just the first `/dist/` in the path) for `src`. */
+function distDirToSrcDir(dir) {
+    const distSeg = `${path.sep}dist${path.sep}`;
+    const idx = dir.lastIndexOf(distSeg);
+    if (idx === -1) {
+        return dir;
+    }
+    return `${dir.slice(0, idx)}${path.sep}src${path.sep}${dir.slice(idx + distSeg.length)}`;
+}
+/**
+ * Resolve a prompt file living in `<module>/prompts/`, relative to the calling
+ * module. At runtime the module lives under `dist/`, but the prompts are shipped
+ * under `src/`, so we map `dist`->`src`. The `dist` candidate is tried first so a
+ * future build step that copies prompts into `dist/` works without code changes.
+ */
+export function resolvePromptFile(moduleUrl, fileName) {
+    const byFileName = resolveCache.get(moduleUrl) ?? new Map();
+    resolveCache.set(moduleUrl, byFileName);
+    const cached = byFileName.get(fileName);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const dir = path.dirname(fileURLToPath(moduleUrl));
+    const candidates = [
+        path.join(dir, 'prompts', fileName),
+        path.join(distDirToSrcDir(dir), 'prompts', fileName),
+    ];
+    const resolved = candidates.find(fs.existsSync) ?? candidates[candidates.length - 1];
+    byFileName.set(fileName, resolved);
+    return resolved;
+}
+export function loadPromptTemplateFile({ fileName, promptLabel, }) {
+    if (!path.isAbsolute(fileName)) {
+        throw new Error(`${promptLabel} prompt template path must be absolute (resolve it with resolvePromptFile first), got: ${fileName}`);
+    }
+    const cached = promptCache.get(fileName);
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        const contents = fs.readFileSync(fileName, 'utf8');
+        promptCache.set(fileName, contents);
+        return contents;
+    }
+    catch (error) {
+        logger.error(`Failed to load ${promptLabel} prompt template`, {
+            error: error instanceof Error ? error.message : String(error),
+            promptPath: fileName,
+        });
+        throw error;
+    }
+}
+export function fillPromptTemplate(template, variables) {
+    return template.replace(/\$([A-Z_][A-Z0-9_]*)/g, (match, varName) => {
+        return variables[varName] ?? match;
+    });
+}

package/sandbox/dist/core/reactions.js

@@ -0,0 +1,36 @@
+import { logger } from './logging.js';
+export async function removeIssueCommentReaction({ octokit, owner, repo, commentId, reactionId, warnMessage, logMeta, }) {
+    try {
+        await octokit.rest.reactions.deleteForIssueComment({
+            owner,
+            repo,
+            comment_id: commentId,
+            reaction_id: reactionId,
+        });
+        return true;
+    }
+    catch (error) {
+        logger.warn(warnMessage, {
+            ...(logMeta ?? {}),
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+export async function removeIssueCommentReactionIfPresent({ octokit, owner, repo, commentId, reactionId, warnMessage, successMessage, logMeta, }) {
+    if (!commentId || !reactionId) {
+        return;
+    }
+    const removed = await removeIssueCommentReaction({
+        octokit,
+        owner,
+        repo,
+        commentId,
+        reactionId,
+        warnMessage,
+        logMeta,
+    });
+    if (removed && successMessage) {
+        logger.info(successMessage, logMeta ?? {});
+    }
+}

package/sandbox/dist/core/regexp.js

@@ -0,0 +1,3 @@
+export function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/sandbox/dist/core/repository-map.js

@@ -0,0 +1 @@
+export { APP_LABEL_ALIASES, APP_TO_ROUTE_SELECTORS, findIntegrationRoute, findIntegrationRoutes, findIssueRoute, findOwningRoutes, findRepositoryRoutes, findRepositoryTarget, INTEGRATION_LABEL_ALIASES, INTEGRATION_ROUTES, PRODUCT_LABEL_ALIASES, PRODUCT_ROUTES, RESOLUTION_PRECEDENCE, TEAM_LABEL_ALIASES, TEAM_TO_ROUTE_SELECTORS, } from 'doistbot-issue-routing';

package/sandbox/dist/core/repository-resolver.js

@@ -0,0 +1 @@
+export { isKnownIssueRoutingLabel, resolveIssueRepositories } from 'doistbot-issue-routing';

package/sandbox/dist/core/retry.js

@@ -0,0 +1,29 @@
+/** Default per-attempt delays for retrying transient HTTP failures. */
+export const HTTP_RETRY_DELAYS_MS = [250, 500, 1000];
+/** True for HTTP errors that are typically worth retrying: 429 and any 5xx. */
+function isTransientHttpError(error) {
+    const status = error?.status;
+    return typeof status === 'number' && (status === 429 || (status >= 500 && status < 600));
+}
+/**
+ * Retries `fn` on errors classified as retryable, sleeping between attempts.
+ * Total attempts = 1 + delaysMs.length. Throws immediately on a non-retryable
+ * error, or after the budget is exhausted (re-throwing the last error).
+ *
+ * Defaults match HTTP usage (429 / 5xx with exponential backoff). Pass
+ * `delaysMs` / `isRetryable` to retry against a different signal.
+ */
+export async function withRetry(fn, delaysMs = HTTP_RETRY_DELAYS_MS, isRetryable = isTransientHttpError) {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (!isRetryable(error) || attempt >= delaysMs.length)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt]));
+            attempt++;
+        }
+    }
+}

package/sandbox/dist/core/s3-utils.js

@@ -0,0 +1,42 @@
+import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { PRESIGN_EXPIRY_SECONDS } from './snapshot-helpers.js';
+/**
+ * Upload files to S3 and generate presigned download URLs.
+ * Skips entries with empty body. Returns the S3 keys and presigned URLs
+ * keyed by each file's `name`.
+ */
+export async function uploadAndPresign({ bucket, files, expiresIn = PRESIGN_EXPIRY_SECONDS, }) {
+    const seen = new Set();
+    for (const file of files) {
+        if (seen.has(file.name)) {
+            throw new Error(`Duplicate file name: "${file.name}"`);
+        }
+        seen.add(file.name);
+    }
+    const s3 = new S3Client({});
+    const s3Keys = {};
+    const presignedUrls = {};
+    for (const file of files) {
+        s3Keys[file.name] = '';
+        presignedUrls[file.name] = '';
+    }
+    for (const file of files) {
+        if (!file.body)
+            continue;
+        await s3.send(new PutObjectCommand({
+            Bucket: bucket,
+            Key: file.key,
+            Body: file.body,
+            ContentType: file.contentType,
+        }));
+        s3Keys[file.name] = file.key;
+        presignedUrls[file.name] = await getSignedUrl(s3, new GetObjectCommand({ Bucket: bucket, Key: file.key }), { expiresIn });
+    }
+    const prefix = files[0]?.key.split('/').slice(0, -1).join('/');
+    return {
+        s3Path: `s3://${bucket}/${prefix ? prefix + '/' : ''}`,
+        s3Keys,
+        presignedUrls,
+    };
+}

package/sandbox/dist/core/shared.js

@@ -0,0 +1,124 @@
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { App, Octokit } from 'octokit';
+import { WORKSPACE_DIR } from './environment.js';
+import { logger } from './logging.js';
+export function resolveWriteOctokit({ githubToken, fallbackOctokit, }) {
+    if (!githubToken) {
+        return fallbackOctokit;
+    }
+    return new Octokit({ auth: githubToken });
+}
+/**
+ * Creates the GitHub clients used by sandbox tasks.
+ * `readOctokit` uses the GitHub App installation.
+ * `writeOctokit` uses the doistbot PAT when configured, otherwise falls back to `readOctokit`.
+ */
+export async function createGitHubClients(ctx) {
+    const app = new App({
+        appId: ctx.appId,
+        privateKey: ctx.privateKey,
+    });
+    const readOctokit = await app.getInstallationOctokit(ctx.installationId);
+    const writeOctokit = resolveWriteOctokit({
+        githubToken: ctx.githubToken,
+        fallbackOctokit: readOctokit,
+    });
+    return { app, readOctokit, writeOctokit };
+}
+/**
+ * Clones a repository to the workspace directory using GitHub App credentials.
+ *
+ * Always fetches via `pull/<num>/head` — works uniformly for open and
+ * closed/merged PRs (GitHub preserves the ref forever) and skips downloading
+ * the default branch, which we never need for review purposes.
+ */
+export async function cloneRepository({ app, owner, repo, prNumber, installationId, depth = 50, }) {
+    await cloneToPath({
+        app,
+        owner,
+        repo,
+        installationId,
+        targetPath: WORKSPACE_DIR,
+        prNumber,
+        depth,
+    });
+}
+async function prepareGitClone(params) {
+    const { app, owner, repo, installationId, targetPath } = params;
+    const token = await app.octokit.auth({ type: 'installation', installationId });
+    const repoUrl = `https://github.com/${owner}/${repo}.git`;
+    const credentials = Buffer.from(`x-access-token:${token.token}`).toString('base64');
+    const authHeader = `http.extraheader=Authorization: Basic ${credentials}`;
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    return { repoUrl, authHeader };
+}
+/**
+ * Initializes a repo at `targetPath` and fetches just the PR's head ref.
+ * Shared utility for any task that needs the working tree at a PR's
+ * head SHA without the default-branch overhead.
+ */
+export async function cloneToPath({ app, owner, repo, installationId, targetPath, prNumber, depth = 1, }) {
+    const { repoUrl, authHeader } = await prepareGitClone({
+        app,
+        owner,
+        repo,
+        installationId,
+        targetPath,
+    });
+    const steps = [
+        { args: ['init', targetPath], label: 'init' },
+        { args: ['-C', targetPath, 'remote', 'add', 'origin', repoUrl], label: 'remote-add' },
+        {
+            args: [
+                '-C',
+                targetPath,
+                '-c',
+                authHeader,
+                'fetch',
+                '--depth',
+                String(depth),
+                'origin',
+                `pull/${prNumber}/head:pr-${prNumber}`,
+            ],
+            label: 'fetch',
+        },
+        { args: ['-C', targetPath, 'checkout', `pr-${prNumber}`], label: 'checkout' },
+    ];
+    for (const step of steps) {
+        const stepResult = spawnSync('git', step.args, { encoding: 'utf8', stdio: 'pipe' });
+        if (stepResult.error || stepResult.status !== 0) {
+            const detail = cloneFailureDetail(stepResult);
+            throw new Error(`Failed to clone ${owner}/${repo} (${step.label}): ${detail}`);
+        }
+    }
+    logger.info('Repository cloned via PR ref', { owner, repo, prNumber, targetPath });
+}
+function cloneFailureDetail(result) {
+    if (result.error) {
+        return result.error.message;
+    }
+    const stderr = typeof result.stderr === 'string' ? result.stderr : '';
+    return stderr.trim().slice(0, 500) || `git exited with status ${result.status}`;
+}
+/**
+ * Clones a repository's default branch to `targetPath`. Used by tasks that
+ * need code context not tied to a specific PR (e.g. persist-logs investigates
+ * issues against the latest main).
+ */
+export async function cloneDefaultBranchToPath({ app, owner, repo, installationId, targetPath, depth = 1, }) {
+    const { repoUrl, authHeader } = await prepareGitClone({
+        app,
+        owner,
+        repo,
+        installationId,
+        targetPath,
+    });
+    const result = spawnSync('git', ['-c', authHeader, 'clone', '--depth', String(depth), repoUrl, targetPath], { encoding: 'utf8', stdio: 'pipe' });
+    if (result.error || result.status !== 0) {
+        const detail = cloneFailureDetail(result);
+        throw new Error(`Failed to clone ${owner}/${repo}: ${detail}`);
+    }
+    logger.info('Repository cloned (default branch)', { owner, repo, targetPath });
+}

package/sandbox/dist/core/snapshot-helpers.js

@@ -0,0 +1,17 @@
+export const LOG_SNAPSHOT_MARKER = '<!--doistbot-log-snapshot-->';
+export const PRESIGN_EXPIRY_SECONDS = 7 * 24 * 60 * 60; // 7 days (SigV4 max)
+/**
+ * Parses S3 bucket and key list from the hidden metadata comment.
+ * Format: `<!-- s3-keys:bucket:key1,key2,key3,... -->`
+ */
+export function parseS3MetadataFromComment(commentBody) {
+    const match = commentBody.match(/<!-- s3-keys:([^:]+):([^\s]+) -->/);
+    const bucket = match?.[1];
+    const keysRaw = match?.[2];
+    if (!bucket || !keysRaw)
+        return null;
+    const keys = keysRaw.split(',').filter(Boolean);
+    if (keys.length === 0)
+        return null;
+    return { bucket, keys };
+}

package/sandbox/dist/core/span-test-helpers.js

@@ -0,0 +1,13 @@
+import { vi } from 'vitest';
+/**
+ * Shared assertion helper for the model/phase span tests, which all spy on
+ * `logger.info` and assert on the same `phase.*` envelope shape emitted by the
+ * LoggerSpanProcessor.
+ *
+ * Returns the `phase.end` envelopes for the given span name, in call order.
+ */
+export function phaseEnds(infoSpy, name) {
+    return infoSpy.mock.calls
+        .map((call) => call[1])
+        .filter((meta) => meta?.event === 'phase.end' && meta?.name === name);
+}

package/sandbox/dist/core/tool-environment.js

@@ -0,0 +1,83 @@
+/** Prepare credentials for Pi shell tools. */
+export function buildToolEnvironment(extraEnv = {}, inherited = process.env) {
+    const env = { ...inherited };
+    delete env.GH_PACKAGES_TOKEN;
+    Object.assign(env, extraEnv);
+    delete env.GITHUB_TOKEN;
+    delete env.PRIVATE_KEY;
+    delete env.GIT_SSH_SIGNING_KEY;
+    // Tracing runs in the sandbox process; agent tools never need the keys.
+    delete env.LANGFUSE_PUBLIC_KEY;
+    delete env.LANGFUSE_SECRET_KEY;
+    env.GIT_TERMINAL_PROMPT = '0';
+    if (env.GH_TOKEN) {
+        const count = Number(env.GIT_CONFIG_COUNT ?? 0);
+        env.GIT_CONFIG_COUNT = String(count + 2);
+        env[`GIT_CONFIG_KEY_${count}`] = 'credential.https://github.com.helper';
+        env[`GIT_CONFIG_VALUE_${count}`] = '';
+        env[`GIT_CONFIG_KEY_${count + 1}`] = 'credential.https://github.com.helper';
+        env[`GIT_CONFIG_VALUE_${count + 1}`] = '!gh auth git-credential';
+    }
+    env.DD_API_KEY = env.DD_API_KEY ?? env.DATADOG_API_KEY;
+    env.DD_APP_KEY = env.DD_APP_KEY ?? env.DATADOG_APP_KEY;
+    env.DD_SITE = env.DD_SITE?.trim() || env.DATADOG_SITE?.trim() || 'datadoghq.com';
+    return env;
+}
+export function approvedSkillArgs(env = process.env) {
+    if (env.SANDBOX_PROFILE !== 'android')
+        return [];
+    return ['--skill', '/app/apps/sandbox/skills/agent-device/SKILL.md'];
+}
+export function buildVerificationEnvironment(inherited = process.env) {
+    const env = {};
+    const names = [
+        'PATH',
+        'HOME',
+        'USER',
+        'LOGNAME',
+        'SHELL',
+        'TMPDIR',
+        'TMP',
+        'TEMP',
+        'LANG',
+        'TZ',
+        'CI',
+        'TERM',
+        'JAVA_HOME',
+        'JDK_HOME',
+        'ANDROID_HOME',
+        'ANDROID_SDK_ROOT',
+        'ANDROID_NDK_HOME',
+        'GRADLE_USER_HOME',
+        'GRADLE_OPTS',
+        'JAVA_OPTS',
+        'NODE_OPTIONS',
+        'NPM_CONFIG_CACHE',
+        'npm_config_cache',
+        'PNPM_HOME',
+        'PYTHONPATH',
+        'PYTHONHOME',
+        'VIRTUAL_ENV',
+        'UV_CACHE_DIR',
+        'PIP_CACHE_DIR',
+        'XDG_CACHE_HOME',
+        'XDG_CONFIG_HOME',
+    ];
+    for (const [name, value] of Object.entries(inherited)) {
+        if (names.includes(name) || name.startsWith('LC_'))
+            env[name] = value;
+    }
+    // Private submodules use the scoped installation token and a fixed Git helper.
+    env.GH_TOKEN = inherited.GH_TOKEN;
+    env.GH_PACKAGES_TOKEN = inherited.GH_PACKAGES_TOKEN;
+    env.GH_HOST = 'github.com';
+    env.GIT_TERMINAL_PROMPT = '0';
+    if (env.GH_TOKEN) {
+        env.GIT_CONFIG_COUNT = '2';
+        env.GIT_CONFIG_KEY_0 = 'credential.https://github.com.helper';
+        env.GIT_CONFIG_VALUE_0 = '';
+        env.GIT_CONFIG_KEY_1 = 'credential.https://github.com.helper';
+        env.GIT_CONFIG_VALUE_1 = '!gh auth git-credential';
+    }
+    return env;
+}

package/sandbox/dist/core/tool-output.js

@@ -0,0 +1,18 @@
+import { writeSync } from 'node:fs';
+import { scrubPii } from './pii-scrubber.js';
+export function safeToolOutput(text) {
+    for (const [name, secret] of Object.entries(process.env)) {
+        if (/(?:KEY|TOKEN|PASSWORD|SECRET)$/.test(name) && secret && secret.length >= 8) {
+            text = text.split(secret).join('[REDACTED_SECRET]');
+        }
+    }
+    return scrubPii(text);
+}
+export function writeToolRecord(record) {
+    // Pi redirects process.stdout in JSON mode. Keep protocol records on stdout.
+    writeSync(1, `${JSON.stringify(record)}\n`);
+}
+export function boundedToolOutput(text, limit = 24_000) {
+    const marker = '\n[Output truncated]';
+    return text.length <= limit ? text : text.slice(0, limit - marker.length) + marker;
+}

package/sandbox/dist/core/tracing-setup.js

@@ -0,0 +1,92 @@
+import { isDefaultExportSpan, LangfuseSpanProcessor } from '@langfuse/otel';
+import { context, SpanStatusCode, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { BasicTracerProvider, } from '@opentelemetry/sdk-trace-base';
+import { LoggerSpanProcessor } from './logger-span-processor.js';
+import { SANDBOX_TRACER_NAME } from './tracing.js';
+// Upper bound on the exit flush, well inside ECS's 30s stop timeout.
+const EXIT_FLUSH_TIMEOUT_MS = 5_000;
+let provider;
+let shutdownPromise;
+// A flush exports ended spans only. Tracking the open ones lets an abnormal
+// exit end them first, so the span a run was stuck in is not lost.
+const openSpans = new Set();
+const openSpanTracker = {
+    onStart(span) {
+        openSpans.add(span);
+    },
+    onEnd(span) {
+        openSpans.delete(span);
+    },
+    async forceFlush() { },
+    async shutdown() { },
+};
+// The base URL is required too: without it the SDK falls back to Langfuse cloud.
+export function isLangfuseTracingEnabled(env = process.env) {
+    return Boolean(env.LANGFUSE_PUBLIC_KEY?.trim() &&
+        env.LANGFUSE_SECRET_KEY?.trim() &&
+        env.LANGFUSE_BASE_URL?.trim());
+}
+// The SDK's default filter keeps only gen_ai spans. It would drop workflow
+// phases such as review.multi-focus and leave the model spans under them
+// pointing at a parent Langfuse never receives.
+export function shouldExportToLangfuse({ otelSpan }) {
+    return (otelSpan.instrumentationScope.name === SANDBOX_TRACER_NAME || isDefaultExportSpan(otelSpan));
+}
+export function setupTracing() {
+    if (provider)
+        return;
+    const spanProcessors = [openSpanTracker, new LoggerSpanProcessor()];
+    const langfuseEnabled = isLangfuseTracingEnabled();
+    if (langfuseEnabled) {
+        spanProcessors.push(new LangfuseSpanProcessor({ shouldExportSpan: shouldExportToLangfuse }));
+    }
+    context.setGlobalContextManager(new AsyncLocalStorageContextManager());
+    provider = new BasicTracerProvider({ spanProcessors });
+    trace.setGlobalTracerProvider(provider);
+    // Covers the natural-exit paths (tasks that return or set process.exitCode).
+    // Tasks that call process.exit() directly must await shutdownTracing() first,
+    // or buffered Langfuse spans are silently dropped.
+    process.once('beforeExit', () => {
+        shutdownTracing().catch(() => undefined);
+    });
+    if (langfuseEnabled)
+        flushTracingOnAbnormalExit();
+}
+// Crashes and ECS stops (SIGTERM) skip `beforeExit`, so failed and timed-out
+// runs would lose their traces. These listeners end the spans still in flight
+// with an error, flush, and exit. They replace Node's default handling, so
+// they report the error and exit with the codes Node would use.
+export function flushTracingOnAbnormalExit(target = process) {
+    function exitAfterFlush(code, reason) {
+        setTimeout(() => target.exit(code), EXIT_FLUSH_TIMEOUT_MS).unref();
+        for (const span of [...openSpans]) {
+            span.setStatus({ code: SpanStatusCode.ERROR, message: reason });
+            span.end();
+        }
+        // shutdownTracing() never rejects.
+        shutdownTracing().then(() => target.exit(code));
+    }
+    function reportAndExit(error) {
+        const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+        target.stderr.write(`${detail}\n`);
+        exitAfterFlush(1, 'Process crashed before the span ended');
+    }
+    target.once('uncaughtException', reportAndExit);
+    target.once('unhandledRejection', reportAndExit);
+    target.once('SIGTERM', () => exitAfterFlush(143, 'Task stopped before the span ended'));
+}
+// Flushes and shuts down span exporters. Idempotent and never throws — safe to
+// await right before process.exit().
+export function shutdownTracing() {
+    const active = provider;
+    if (!active)
+        return Promise.resolve();
+    // Shut down even when the flush fails, so exporters never stay registered.
+    shutdownPromise ??= active
+        .forceFlush()
+        .catch(() => undefined)
+        .then(() => active.shutdown())
+        .catch(() => undefined);
+    return shutdownPromise;
+}

package/sandbox/dist/core/tracing.js

@@ -0,0 +1,81 @@
+import { context, SpanStatusCode, trace } from '@opentelemetry/api';
+// recordDecision/recordEvent emit directly (bypassing the processor), so they
+// apply the same per-attribute cap themselves to keep large arrays/objects
+// from blowing the log-size budget.
+import { truncateAttrs } from './logger-span-processor.js';
+import { logger } from './logging.js';
+export const SANDBOX_TRACER_NAME = 'doistbot-sandbox';
+const tracer = trace.getTracer(SANDBOX_TRACER_NAME);
+/**
+ * THE phase-boundary API. Works for sequential AND parallel phases — OTel's
+ * async-hooks context manager (registered by setupTracing) parents nested
+ * spans correctly even across Promise.all.
+ *
+ * On throw: records the exception, sets span status ERROR, re-throws.
+ * On normal return: status is left UNSET (OTel's recommended success default;
+ *   the LoggerSpanProcessor maps UNSET → 'ok'). We deliberately do NOT force
+ *   OK, so a callback that returns a failure result (instead of throwing) and
+ *   sets ERROR itself keeps its ERROR status.
+ * Always ends the span.
+ */
+export async function withPhase(name, attributes, fn) {
+    return tracer.startActiveSpan(name, { attributes: { ...attributes, 'doistbot.kind': 'phase' } }, async (span) => {
+        try {
+            return await fn(span);
+        }
+        catch (err) {
+            span.recordException(err);
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Start a tool span manually. The ONE exception to "withPhase everywhere":
+ * pi emits tool start/end across separate async callbacks (onProgress), so
+ * there is no single scope to wrap. Parent = the currently-active span (the
+ * model phase). Caller MUST call `span.end()` when the matching tool_end
+ * arrives (and may `setStatus({ code: ERROR })` first on failure).
+ */
+export function startToolSpan(name, attributes) {
+    return tracer.startSpan(name, { attributes: { ...attributes, 'doistbot.kind': 'tool' } }, context.active());
+}
+// Point-in-time lines bypass OTel spans entirely; they read the active span
+// id only for correlation. Meta is spread FIRST so callers can never clobber
+// the envelope fields (event/name/span_id). Timestamps come from the logging
+// system, never from meta.
+function emitPointInTime(kind, name, meta) {
+    const span = trace.getActiveSpan();
+    logger.info(`${kind}: ${name}`, {
+        ...truncateAttrs(meta),
+        event: kind,
+        name,
+        span_id: span?.spanContext().spanId ?? null,
+    });
+}
+/**
+ * Record a point-in-time decision (branch taken, scope resolved, gate passed)
+ * correlated to the active span. Not a span — no duration.
+ */
+export function recordDecision(name, meta) {
+    emitPointInTime('decision', name, meta);
+}
+/** Generic point-in-time annotation. Same mechanics as recordDecision. */
+export function recordEvent(name, meta) {
+    emitPointInTime('event', name, meta);
+}
+/**
+ * Maps a doistbot provider key to the OTel `gen_ai.provider.name` value
+ * (docs/sandbox-instrumentation.md). Only `gemini` has a standard name
+ * (`gcp.gemini`); the OpenRouter-routed keys (`grok`, `zai`, `deepseek`) have none, so
+ * they pass through. Single source so every span site stays consistent.
+ */
+export function genAiProviderName(provider) {
+    return provider === 'gemini' ? 'gcp.gemini' : provider;
+}