@vibes.diy/api-svc 14.1.21 → 14.1.22

package/intern/agent-debug-tools.js

@@ -0,0 +1,676 @@
+import { Result, exception2Result } from "@adviser/cement";
+import { and, eq, sql } from "drizzle-orm";
+import { getSkillText } from "@vibes.diy/prompts";
+import { isActiveDeferredIntents, isActivePosture } from "@vibes.diy/api-types";
+import { readComposedSettings, readComposedSettingsForApp, readComposedSettingsOwnerForApp, writeAppSettingItems, } from "../public/app-setting-items.js";
+import { postAppSettingEvent } from "../public/app-settings-sql-upsert.js";
+import { remoteDocChangedFanOut } from "../public/app-documents-broadcast.js";
+import { readAppLogsPage } from "../public/app-logs.js";
+import { authorizeSlugOwner } from "../public/authorize-slug-owner.js";
+import { getBindingFlags } from "../public/unpublished-binding.js";
+import { getDocForCaller, queryDocsForCaller, listDbNamesForCaller } from "../public/app-documents-read-eventos.js";
+import { putDocForCaller, deleteDocForCaller } from "../public/app-documents-write-eventos.js";
+import { loadSelectedBackend } from "./load-selected-backend.js";
+import { loadVersionItems } from "./build-version-ordinal.js";
+import { loadVersionTimeline } from "./version-timeline.js";
+import { skillGuideIndex } from "./agent-file-tools.js";
+import { WORK_TOOL_RESULT_MAX_CHARS } from "./work-tools.js";
+import { MAX_TOOL_RESULT_CHARS } from "./llm-tool-loop.js";
+import { resolveChatApp } from "./agent-actor.js";
+export const READ_APP_LOGS_TOOL_NAME = "read_app_logs";
+export const READ_RELEASE_STATE_TOOL_NAME = "read_release_state";
+export const READ_SCHEDULE_STATUS_TOOL_NAME = "read_schedule_status";
+export const LIST_DATABASES_TOOL_NAME = "list_databases";
+export const QUERY_DOCS_TOOL_NAME = "query_docs";
+export const GET_DOC_TOOL_NAME = "get_doc";
+export const PUT_DOC_TOOL_NAME = "put_doc";
+export const DELETE_DOC_TOOL_NAME = "delete_doc";
+export const RETRACT_DEFERRED_INTENT_TOOL_NAME = "retract_deferred_intent";
+export const CALL_OWN_API_TOOL_NAME = "call_own_api";
+const DEBUGGING_SKILL_NAME = "debugging";
+export const AGENT_DEBUG_TOOL_NAMES = new Set([
+    READ_APP_LOGS_TOOL_NAME,
+    READ_RELEASE_STATE_TOOL_NAME,
+    READ_SCHEDULE_STATUS_TOOL_NAME,
+    LIST_DATABASES_TOOL_NAME,
+    QUERY_DOCS_TOOL_NAME,
+    GET_DOC_TOOL_NAME,
+    PUT_DOC_TOOL_NAME,
+    DELETE_DOC_TOOL_NAME,
+    RETRACT_DEFERRED_INTENT_TOOL_NAME,
+    CALL_OWN_API_TOOL_NAME,
+]);
+const MAX_SINCE_MINUTES = 1440;
+const DEFAULT_SINCE_MINUTES = 60;
+const LOG_PAGE_LIMIT = 40;
+const LOG_BODY_CHARS = 400;
+const LOG_BODY_MARKER = "…";
+const LOG_LEVELS = new Set(["debug", "info", "warn", "error"]);
+const DOC_PAGE_DEFAULT_LIMIT = 10;
+const DOC_PAGE_MAX_LIMIT = 20;
+const DOC_BODY_CHARS = 1024;
+const OWN_API_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+export function createAgentDebugTools(vctx, args) {
+    const scopeOwner = args.actor.scope?.ownerHandle ?? args.actor.ownerHandle;
+    const scopeSlug = args.actor.scope?.appSlug;
+    const definitions = [
+        {
+            type: "function",
+            function: {
+                name: READ_APP_LOGS_TOOL_NAME,
+                description: "Read what the deployed app has been recording about itself — the lines its server code and its page wrote " +
+                    "with the platform's own log call. Read this when the person says something is not working, or after a " +
+                    "change that added server work, so what you tell them about the live app comes from the app rather than " +
+                    "from the code you expect it to be running. Newest window first; page on with the cursor it returns.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        level: {
+                            type: "string",
+                            enum: ["debug", "info", "warn", "error"],
+                            description: "Keep only lines at this level. Omit for every level.",
+                        },
+                        sinceMinutes: {
+                            type: "number",
+                            description: "How far back to look, in minutes. Defaults to the last hour; the widest window is a day.",
+                        },
+                        cursor: { type: "string", description: "Continue from a previous call's nextCursor." },
+                    },
+                    required: [],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: READ_RELEASE_STATE_TOOL_NAME,
+                description: "Read which version of this app is actually live: what is published, whether newer work is waiting behind " +
+                    "it, whether the owner pinned a version or took the app down, who the app lets in, and whether the live " +
+                    "version carries its record rules and its server file. Read this before telling the person what is live, " +
+                    "and before saying a change they asked for is already in the app.",
+                parameters: { type: "object", properties: {}, required: [], additionalProperties: false },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: READ_SCHEDULE_STATUS_TOOL_NAME,
+                description: "Read whether this app's scheduled server work is running: when it last ran, when it is next expected, and " +
+                    "the error it last reported. Read this when the person expects something to happen on its own and says it " +
+                    "has not.",
+                parameters: { type: "object", properties: {}, required: [], additionalProperties: false },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: LIST_DATABASES_TOOL_NAME,
+                description: "List the record collections this app has actually written to. Read this before looking at records, so you " +
+                    "work from the collections that exist rather than the ones the code implies.",
+                parameters: { type: "object", properties: {}, required: [], additionalProperties: false },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: QUERY_DOCS_TOOL_NAME,
+                description: "Read a page of this app's records, exactly as the person whose app this is would see them in the running " +
+                    "app. Read this when what the person describes and what the code does disagree — the records say which one " +
+                    "the data matches. Pages are small; continue with the cursor it returns, and keep going while it returns " +
+                    "one, because a page that filtered everything out can still have more behind it.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        dbName: { type: "string", description: "The collection to read, from list_databases." },
+                        limit: { type: "number", description: "Records per page, up to 20. Defaults to 10." },
+                        after: { type: "string", description: "Continue from a previous call's next." },
+                        field: { type: "string", description: "Narrow to records indexed on this field." },
+                        key: { description: "With field, keep only records whose field equals this value." },
+                        prefix: { description: "With field, keep only records whose field starts with this value." },
+                    },
+                    required: ["dbName"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: GET_DOC_TOOL_NAME,
+                description: "Read one record by its id, as the person whose app this is would see it. Read the record before saying " +
+                    "anything about what it contains.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        dbName: { type: "string", description: "The collection the record is in." },
+                        docId: { type: "string", description: "The record's id." },
+                    },
+                    required: ["dbName", "docId"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: PUT_DOC_TOOL_NAME,
+                description: "Save one record, as the person whose app this is. Include the record's id as _id to change a record that " +
+                    "already exists, and leave it out to add a new one. The app's own record rules decide whether the save " +
+                    "lands, so a refusal here is the app telling you what it allows. For more than a handful of records, add a " +
+                    "route to the app's server file and run it once instead — read /skills/debugging.md for how.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        dbName: { type: "string", description: "The collection to save into." },
+                        doc: { type: "object", description: "The whole record. Its _id, when present, names the record to change." },
+                    },
+                    required: ["dbName", "doc"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: DELETE_DOC_TOOL_NAME,
+                description: "Remove one record, as the person whose app this is. The app's own record rules decide whether the removal " +
+                    "lands. Recipients who already hold a copy keep it; this stops it being served from here on.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        dbName: { type: "string", description: "The collection the record is in." },
+                        docId: { type: "string", description: "The record's id." },
+                    },
+                    required: ["dbName", "docId"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: CALL_OWN_API_TOOL_NAME,
+                description: "Call one of this app's own server routes as the person whose app this is. The route runs the live " +
+                    "release's backend.js fetch handler with the owner's identity, so a route written for bulk record work, a " +
+                    "health check or a data export answers here the way it answers the owner's curl. Read the release state " +
+                    "first when unsure which routes the live version carries. Answers with the route's status, its content " +
+                    "type and its body text, marked when the body was longer than this result holds.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        method: {
+                            type: "string",
+                            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                            description: "The HTTP method the route expects.",
+                        },
+                        path: {
+                            type: "string",
+                            description: "The part of the route after /_api/, with no leading slash. A query string is fine.",
+                        },
+                        body: { type: "string", description: "The request body, for a method that carries one." },
+                        contentType: { type: "string", description: "The body's content type. Defaults to application/json." },
+                    },
+                    required: ["method", "path"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: RETRACT_DEFERRED_INTENT_TOOL_NAME,
+                description: "Take back a capability this app said it would add later, once it is either built or no longer wanted. This " +
+                    "is the same act as the owner dismissing the offer themselves, so use it when the work is done or the " +
+                    "person says they do not want it.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        kind: {
+                            type: "string",
+                            enum: ["access", "backend"],
+                            description: "Which offer to take back: record rules, or server work.",
+                        },
+                    },
+                    required: ["kind"],
+                    additionalProperties: false,
+                },
+            },
+        },
+    ];
+    async function appInScope() {
+        if (args.chatId !== undefined) {
+            const rApp = await resolveChatApp(vctx, args.actor, args.chatId);
+            if (rApp.isErr())
+                return { refusal: JSON.stringify(rApp.Err().refusal) };
+            return { app: rApp.Ok() };
+        }
+        if (scopeSlug !== undefined)
+            return { app: { ownerHandle: scopeOwner, appSlug: scopeSlug } };
+        return {
+            refusal: JSON.stringify({
+                ok: false,
+                reason: "no-app-in-scope",
+                message: "This conversation is not about one specific app yet.",
+            }),
+        };
+    }
+    let guideIntroduced = false;
+    async function withGuide(payload) {
+        if (guideIntroduced)
+            return toolJson(payload);
+        const loaded = await exception2Result(() => (args.loadSkill ?? getSkillText)(DEBUGGING_SKILL_NAME));
+        if (loaded.isErr())
+            return toolJson(payload);
+        guideIntroduced = true;
+        return toolJson({ ...payload, guide: skillGuideIndex(DEBUGGING_SKILL_NAME, loaded.Ok()) });
+    }
+    const failedWithGuide = (message) => withGuide({ ok: false, reason: "failed", message });
+    const deniedWithGuide = (message) => withGuide({ ok: false, reason: "not-owner", message });
+    const invalidWithGuide = (message) => withGuide({ ok: false, reason: "invalid-input", message });
+    const forbiddenWithGuide = (explanation) => withGuide({ ok: false, reason: "forbidden", explanation });
+    const executor = async (input) => {
+        const scoped = await appInScope();
+        if (scoped.refusal !== undefined)
+            return Result.Ok(scoped.refusal);
+        const app = scoped.app;
+        if (input.call.name === READ_APP_LOGS_TOOL_NAME) {
+            const auth = await exception2Result(() => authorizeSlugOwner(vctx, { ownerHandle: app.ownerHandle, appSlug: app.appSlug, userId: args.actor.userId }));
+            if (auth.isErr())
+                return failedWithGuide("Could not read this app's logs just now.");
+            if (auth.Ok()?.isOwner !== true) {
+                return deniedWithGuide("Only this app's owner can read its logs.");
+            }
+            const parsedArgs = parseArgs(input.call.arguments);
+            const sinceMinutes = clampSinceMinutes(parsedArgs.sinceMinutes);
+            const level = typeof parsedArgs.level === "string" && LOG_LEVELS.has(parsedArgs.level) ? parsedArgs.level : undefined;
+            const cursor = typeof parsedArgs.cursor === "string" && parsedArgs.cursor !== "" ? parsedArgs.cursor : undefined;
+            const rPage = await readAppLogsPage(vctx, {
+                ownerHandle: app.ownerHandle,
+                appSlug: app.appSlug,
+                sinceTs: new Date(Date.now() - sinceMinutes * 60_000).toISOString(),
+                ...(cursor === undefined ? {} : { sinceId: cursor }),
+                ...(level === undefined ? {} : { level }),
+                limit: LOG_PAGE_LIMIT,
+            });
+            if (rPage.isErr())
+                return failedWithGuide("Could not read this app's logs just now.");
+            const page = rPage.Ok();
+            return Result.Ok(boundedLogEventsJson({ ok: true, sinceMinutes }, page.events.map((e) => ({
+                id: e.id,
+                ts: e.ts,
+                lane: e.lane,
+                level: e.level,
+                trigger: e.trigger,
+                fsId: e.fsId,
+                body: truncateBody(e.body),
+            })), page.nextCursor));
+        }
+        if (input.call.name === READ_RELEASE_STATE_TOOL_NAME) {
+            const r = await exception2Result(() => readReleaseState(vctx, app, args.chatId));
+            if (r.isErr() || r.Ok().ok === false)
+                return failedWithGuide("Could not read this app's release state just now.");
+            return toolJson({ ok: true, ...r.Ok().state });
+        }
+        if (input.call.name === READ_SCHEDULE_STATUS_TOOL_NAME) {
+            const cp = vctx.backendControlPlane;
+            if (cp === undefined)
+                return failedWithGuide("Could not read this app's schedule just now.");
+            const rStatus = await exception2Result(() => cp.tickStatus(app.ownerHandle, app.appSlug));
+            if (rStatus.isErr())
+                return failedWithGuide("Could not read this app's schedule just now.");
+            return toolJson({ ok: true, ...rStatus.Ok() });
+        }
+        const caller = {
+            userId: args.actor.userId,
+            ownerHandle: app.ownerHandle,
+            appSlug: app.appSlug,
+            adminMode: false,
+            actingHandle: args.actor.ownerHandle,
+            fanOutDocChanged: remoteDocChangedFanOut,
+        };
+        if (input.call.name === LIST_DATABASES_TOOL_NAME) {
+            const r = await exception2Result(() => listDbNamesForCaller(vctx, {
+                userId: args.actor.userId,
+                ownerHandle: app.ownerHandle,
+                appSlug: app.appSlug,
+                adminMode: false,
+            }));
+            if (r.isErr())
+                return failedWithGuide("Could not read this app's record collections just now.");
+            const answer = r.Ok();
+            if (answer.kind === "denied")
+                return deniedWithGuide(answer.message);
+            return toolJson({ ok: true, dbNames: answer.dbNames });
+        }
+        if (input.call.name === QUERY_DOCS_TOOL_NAME) {
+            const parsedArgs = parseArgs(input.call.arguments);
+            const dbName = stringArg(parsedArgs.dbName);
+            if (dbName === undefined)
+                return invalidWithGuide("dbName is required.");
+            const field = stringArg(parsedArgs.field);
+            const r = await exception2Result(() => queryDocsForCaller(vctx, {
+                ...caller,
+                dbName,
+                limit: clampDocLimit(parsedArgs.limit),
+                ...(stringArg(parsedArgs.after) === undefined ? {} : { after: stringArg(parsedArgs.after) }),
+                ...(field === undefined
+                    ? {}
+                    : {
+                        filter: {
+                            field,
+                            ...(parsedArgs.key === undefined ? {} : { key: parsedArgs.key }),
+                            ...(parsedArgs.prefix === undefined ? {} : { prefix: parsedArgs.prefix }),
+                        },
+                    }),
+            }));
+            if (r.isErr())
+                return failedWithGuide("Could not read this app's records just now.");
+            const answer = r.Ok();
+            if (answer.kind === "denied")
+                return deniedWithGuide(answer.message);
+            return Result.Ok(boundedDocsJson({ ok: true, dbName, ...(answer.next === undefined ? {} : { next: answer.next }) }, answer.docs.map(truncateDoc)));
+        }
+        if (input.call.name === GET_DOC_TOOL_NAME) {
+            const parsedArgs = parseArgs(input.call.arguments);
+            const dbName = stringArg(parsedArgs.dbName);
+            const docId = stringArg(parsedArgs.docId);
+            if (dbName === undefined || docId === undefined)
+                return invalidWithGuide("dbName and docId are required.");
+            const r = await exception2Result(() => getDocForCaller(vctx, { ...caller, dbName, docId }));
+            if (r.isErr())
+                return failedWithGuide("Could not read that record just now.");
+            const answer = r.Ok();
+            if (answer.kind === "denied")
+                return deniedWithGuide(answer.message);
+            if (answer.kind === "not-found")
+                return toolJson({ ok: true, dbName, docId, found: false });
+            return Result.Ok(boundedDocsJson({ ok: true, dbName, docId, found: true }, [truncateDoc({ _id: answer.docId, ...answer.doc })]));
+        }
+        if (input.call.name === PUT_DOC_TOOL_NAME) {
+            const parsedArgs = parseArgs(input.call.arguments);
+            const dbName = stringArg(parsedArgs.dbName);
+            const doc = parsedArgs.doc;
+            if (dbName === undefined || typeof doc !== "object" || doc === null || Array.isArray(doc))
+                return invalidWithGuide("dbName and a doc object are required.");
+            const body = doc;
+            const bodyId = stringArg(body._id);
+            const r = await exception2Result(() => putDocForCaller(vctx, { ...caller, dbName, doc: body, ...(bodyId === undefined ? {} : { docId: bodyId }) }));
+            if (r.isErr())
+                return failedWithGuide("Could not save that record just now.");
+            const answer = r.Ok();
+            if (answer.kind === "denied")
+                return forbiddenWithGuide(answer.message);
+            return toolJson({ ok: true, dbName, docId: answer.docId });
+        }
+        if (input.call.name === DELETE_DOC_TOOL_NAME) {
+            const parsedArgs = parseArgs(input.call.arguments);
+            const dbName = stringArg(parsedArgs.dbName);
+            const docId = stringArg(parsedArgs.docId);
+            if (dbName === undefined || docId === undefined)
+                return invalidWithGuide("dbName and docId are required.");
+            const r = await exception2Result(() => deleteDocForCaller(vctx, { ...caller, dbName, docId }));
+            if (r.isErr())
+                return failedWithGuide("Could not remove that record just now.");
+            const answer = r.Ok();
+            if (answer.kind === "denied")
+                return forbiddenWithGuide(answer.message);
+            return toolJson({ ok: true, dbName, docId: answer.docId });
+        }
+        if (input.call.name === CALL_OWN_API_TOOL_NAME) {
+            const auth = await exception2Result(() => authorizeSlugOwner(vctx, { ownerHandle: app.ownerHandle, appSlug: app.appSlug, userId: args.actor.userId }));
+            if (auth.isErr())
+                return failedWithGuide("Could not reach this app's server routes just now.");
+            if (auth.Ok()?.isOwner !== true) {
+                return deniedWithGuide("Only this app's owner can run its server routes from here.");
+            }
+            const call = vctx.backendOwnerApiFetch;
+            if (call === undefined) {
+                return failedWithGuide("Running this app's server routes is not available in this environment.");
+            }
+            const parsedArgs = parseArgs(input.call.arguments);
+            const method = stringArg(parsedArgs.method)?.toUpperCase();
+            if (method === undefined || !OWN_API_METHODS.has(method)) {
+                return invalidWithGuide("method must be one of GET, POST, PUT, PATCH or DELETE.");
+            }
+            const path = stringArg(parsedArgs.path);
+            if (path === undefined)
+                return invalidWithGuide("path is required.");
+            if (path.startsWith("/"))
+                return invalidWithGuide("path is the part after /_api/, so it starts without a slash.");
+            if (path.includes("//") || path.includes("..") || path.includes("#") || path.includes("\\")) {
+                return invalidWithGuide("path names one route on this app: no doubled slashes, dot segments or fragments.");
+            }
+            if (!ownApiPathIsLiteral(path)) {
+                return invalidWithGuide("path must name the route literally: no percent-encoded or escaped path segments.");
+            }
+            const body = stringArg(parsedArgs.body);
+            if (body !== undefined && (method === "GET" || method === "HEAD")) {
+                return invalidWithGuide(`A ${method} carries no body; put what the route needs in the path's query string.`);
+            }
+            const r = await exception2Result(() => call({
+                ownerHandle: app.ownerHandle,
+                appSlug: app.appSlug,
+                userId: args.actor.userId,
+                method,
+                path,
+                ...(body === undefined ? {} : { body, contentType: stringArg(parsedArgs.contentType) ?? "application/json" }),
+            }));
+            if (r.isErr())
+                return failedWithGuide("Could not reach this app's server routes just now.");
+            const answer = r.Ok();
+            return toolJson(fitOwnApiToolResult({
+                method,
+                path,
+                status: answer.status,
+                contentType: answer.contentType,
+                bodyText: answer.bodyText,
+                truncated: answer.truncated,
+            }));
+        }
+        if (input.call.name === RETRACT_DEFERRED_INTENT_TOOL_NAME) {
+            const parsedArgs = parseArgs(input.call.arguments);
+            const kind = parsedArgs.kind;
+            if (kind !== "access" && kind !== "backend")
+                return invalidWithGuide('kind must be "access" or "backend".');
+            const r = await exception2Result(() => retractDeferredIntent(vctx, app, kind));
+            if (r.isErr())
+                return failedWithGuide("Could not take that offer back just now.");
+            return toolJson({ ok: true, kind, retracted: r.Ok() });
+        }
+        return toolJson({ ok: false, reason: "invalid-input", message: `Unknown tool ${input.call.name}.` });
+    };
+    return { definitions, executor };
+}
+async function readReleaseState(vctx, app, chatId) {
+    const [listing, flags, entries] = await Promise.all([
+        loadVersionItems(vctx, app),
+        getBindingFlags(vctx, app),
+        readComposedSettingsForApp(vctx, app.ownerHandle, app.appSlug),
+    ]);
+    const published = listing.items.find((i) => i.published);
+    let headFsId;
+    if (chatId !== undefined) {
+        const rTimeline = await loadVersionTimeline(vctx, chatId);
+        if (rTimeline.isErr())
+            return { ok: false };
+        const timeline = rTimeline.Ok();
+        headFsId = timeline.length > 0 ? timeline[timeline.length - 1].fsId : undefined;
+    }
+    const tApps = vctx.sql.tables.apps;
+    const publishedRow = published === undefined
+        ? undefined
+        : await vctx.sql.db
+            .select({ fileSystem: tApps.fileSystem })
+            .from(tApps)
+            .where(and(eq(tApps.ownerHandle, app.ownerHandle), eq(tApps.appSlug, app.appSlug), eq(tApps.fsId, published.fsId)))
+            .orderBy(sql `${tApps.releaseSeq} desc`)
+            .limit(1)
+            .then((r) => r[0]);
+    const files = (publishedRow?.fileSystem ?? []);
+    const has = (name) => files.some((f) => f.fileName === name);
+    const backendJsInRelease = has("/backend.js");
+    const loaded = backendJsInRelease ? await loadSelectedBackend(vctx, app.ownerHandle, app.appSlug) : undefined;
+    const backendHandlersUnreadable = backendJsInRelease && loaded?.ok !== true;
+    const posture = entries.find(isActivePosture)?.posture;
+    const deferred = entries.find(isActiveDeferredIntents);
+    return {
+        ok: true,
+        state: {
+            ...(published === undefined ? {} : { publishedFsId: published.fsId, publishedAt: published.created }),
+            ...(flags.lockedFsId === "" ? {} : { lockedFsId: flags.lockedFsId }),
+            unpublished: flags.unpublishedAt !== "",
+            ...(headFsId === undefined ? {} : { headFsId }),
+            draftAhead: headFsId !== undefined && headFsId !== published?.fsId,
+            ...(posture === undefined ? {} : { posture }),
+            accessJsInRelease: has("/access.js"),
+            backendJsInRelease,
+            backendHandlers: backendHandlersUnreadable ? null : loaded !== undefined && loaded.ok ? [...loaded.parsed.handlers] : [],
+            ...(backendHandlersUnreadable ? { backendHandlersUnreadable: true } : {}),
+            ...(deferred === undefined
+                ? {}
+                : {
+                    deferred: {
+                        ...(deferred.access === undefined ? {} : { access: deferred.access }),
+                        ...(deferred.backend === undefined ? {} : { backend: deferred.backend }),
+                    },
+                }),
+        },
+    };
+}
+async function retractDeferredIntent(vctx, app, kind) {
+    const { userId, entries } = await readComposedSettingsOwnerForApp(vctx, app.ownerHandle, app.appSlug);
+    const current = entries.find(isActiveDeferredIntents);
+    if (userId === undefined || current === undefined || current[kind] === undefined)
+        return false;
+    const kept = {
+        type: "active.deferred-intents",
+        ...(kind === "access" || current.access === undefined ? {} : { access: current.access }),
+        ...(kind === "backend" || current.backend === undefined ? {} : { backend: current.backend }),
+    };
+    const key = { userId, ownerHandle: app.ownerHandle, appSlug: app.appSlug };
+    const empty = kept.access === undefined && kept.backend === undefined;
+    await writeAppSettingItems(vctx, key, empty ? { removeKeys: ["active.deferred-intents"] } : { upserts: [kept] });
+    await postAppSettingEvent(vctx, app, await readComposedSettings(vctx, key));
+    return true;
+}
+function boundedDocsJson(envelope, docs) {
+    let kept = docs.length;
+    for (;;) {
+        const omitted = docs.length - kept;
+        const json = JSON.stringify({
+            ...envelope,
+            returned: kept,
+            ...(omitted === 0
+                ? {}
+                : {
+                    omittedForSize: omitted,
+                    hint: `${omitted} more record(s) were left out of this result for size. Narrow the read with field/key, or ask for a smaller limit.`,
+                }),
+            docs: docs.slice(0, kept),
+        });
+        if (json.length <= WORK_TOOL_RESULT_MAX_CHARS || kept === 0)
+            return json;
+        kept = kept - 1;
+    }
+}
+function boundedLogEventsJson(envelope, events, pageCursor) {
+    let kept = events.length;
+    for (;;) {
+        const truncatedCount = events.length - kept;
+        const cursor = truncatedCount === 0 || kept === 0 ? pageCursor : events[kept - 1].id;
+        const json = JSON.stringify({
+            ...envelope,
+            returned: kept,
+            ...(truncatedCount === 0
+                ? {}
+                : {
+                    truncatedCount,
+                    hint: `${truncatedCount} more line(s) were left out of this result for size. Read on from nextCursor, or narrow with level/sinceMinutes.`,
+                }),
+            events: events.slice(0, kept),
+            ...(cursor === null ? {} : { nextCursor: cursor }),
+        });
+        if (json.length <= WORK_TOOL_RESULT_MAX_CHARS || kept === 0)
+            return json;
+        kept = kept - 1;
+    }
+}
+function truncateDoc(doc) {
+    const json = JSON.stringify(doc);
+    if (json === undefined || json.length <= DOC_BODY_CHARS)
+        return doc;
+    const id = typeof doc === "object" && doc !== null ? doc._id : undefined;
+    return {
+        ...(typeof id === "string" ? { _id: id } : {}),
+        _truncated: true,
+        body: `${json.slice(0, DOC_BODY_CHARS)}${LOG_BODY_MARKER}`,
+    };
+}
+function stringArg(raw) {
+    return typeof raw === "string" && raw !== "" ? raw : undefined;
+}
+function clampDocLimit(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0)
+        return DOC_PAGE_DEFAULT_LIMIT;
+    return Math.min(Math.floor(raw), DOC_PAGE_MAX_LIMIT);
+}
+function clampSinceMinutes(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_SINCE_MINUTES;
+    return Math.min(Math.floor(raw), MAX_SINCE_MINUTES);
+}
+function truncateBody(body) {
+    return body.length <= LOG_BODY_CHARS ? body : `${body.slice(0, LOG_BODY_CHARS)}${LOG_BODY_MARKER}`;
+}
+function parseArgs(raw) {
+    const r = exception2Result(() => JSON.parse(raw));
+    if (r.isErr())
+        return {};
+    const parsed = r.Ok();
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+}
+function toolJson(payload) {
+    return Result.Ok(JSON.stringify(payload));
+}
+export function fitOwnApiToolResult(answer) {
+    const envelope = (body) => ({
+        ok: true,
+        method: answer.method,
+        path: answer.path,
+        status: answer.status,
+        ...(answer.contentType === null ? {} : { contentType: answer.contentType }),
+        body,
+        truncated: true,
+    });
+    const overhead = JSON.stringify(envelope("")).length;
+    let body = answer.bodyText;
+    let cut = answer.truncated;
+    const budget = Math.max(0, MAX_TOOL_RESULT_CHARS - overhead - 64);
+    if (body.length > budget) {
+        body = body.slice(0, budget);
+        cut = true;
+    }
+    while (body.length > 0 && JSON.stringify(envelope(body)).length > MAX_TOOL_RESULT_CHARS) {
+        const over = JSON.stringify(envelope(body)).length - MAX_TOOL_RESULT_CHARS;
+        body = body.slice(0, Math.max(0, body.length - Math.max(over, 16)));
+        cut = true;
+    }
+    return {
+        ok: true,
+        method: answer.method,
+        path: answer.path,
+        status: answer.status,
+        ...(answer.contentType === null ? {} : { contentType: answer.contentType }),
+        body,
+        ...(cut ? { truncated: true } : {}),
+    };
+}
+function ownApiPathIsLiteral(path) {
+    const [beforeQuery] = path.split("?");
+    const r = exception2Result(() => new URL(`https://vibe.invalid/${path}`));
+    if (r.isErr())
+        return false;
+    return r.Ok().pathname === `/${beforeQuery}`;
+}
+//# sourceMappingURL=agent-debug-tools.js.map