@ouro.bot/cli 0.1.0-alpha.56 → 0.1.0-alpha.560

package/dist/repertoire/tools-files.js

@@ -0,0 +1,342 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileToolDefinitions = void 0;
+const fs = __importStar(require("fs"));
+const fg = __importStar(require("fast-glob"));
+const path = __importStar(require("path"));
+const identity_1 = require("../heart/identity");
+const file_state_1 = require("../mind/file-state");
+const scrutiny_1 = require("../mind/scrutiny");
+const tools_base_1 = require("./tools-base");
+function resolveLocalToolPath(targetPath) {
+    if (!path.isAbsolute(targetPath)) {
+        return path.resolve((0, identity_1.getRepoRoot)(), targetPath);
+    }
+    return targetPath;
+}
+function buildContextDiff(lines, changeStart, changeEnd, contextSize = 3) {
+    const start = Math.max(0, changeStart - contextSize);
+    const end = Math.min(lines.length, changeEnd + contextSize);
+    const result = [];
+    for (let i = start; i < end; i++) {
+        const lineNum = i + 1;
+        const prefix = (i >= changeStart && i < changeEnd) ? ">" : " ";
+        result.push(`${prefix} ${lineNum} | ${lines[i]}`);
+    }
+    return result.join("\n");
+}
+exports.fileToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "read_file",
+                description: "Read file contents. Results include line numbers. Use offset/limit for large files -- don't read the whole thing if you only need a section. Use this tool before editing any file. When reading code, read enough context to understand the surrounding logic, not just the target line.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string" },
+                        offset: { type: "number", description: "1-based line number to start reading from" },
+                        limit: { type: "number", description: "maximum number of lines to return" },
+                    },
+                    required: ["path"],
+                },
+            },
+        },
+        handler: (a) => {
+            const resolvedPath = resolveLocalToolPath(a.path);
+            const content = fs.readFileSync(resolvedPath, "utf-8");
+            tools_base_1.editFileReadTracker.add(resolvedPath);
+            const offset = a.offset ? parseInt(a.offset, 10) : undefined;
+            const limit = a.limit ? parseInt(a.limit, 10) : undefined;
+            // Record in file state cache for staleness detection
+            try {
+                const mtime = fs.statSync(resolvedPath).mtimeMs;
+                const readContent = (offset === undefined && limit === undefined)
+                    ? content
+                    : content.split("\n").slice(offset ? offset - 1 : 0, limit !== undefined ? (offset ? offset - 1 : 0) + limit : undefined).join("\n");
+                file_state_1.fileStateCache.record(resolvedPath, readContent, mtime, offset, limit);
+            }
+            catch {
+                // stat failed -- skip cache recording
+            }
+            if (offset === undefined && limit === undefined)
+                return content;
+            const lines = content.split("\n");
+            const start = offset ? offset - 1 : 0;
+            const end = limit !== undefined ? start + limit : lines.length;
+            return lines.slice(start, end).join("\n");
+        },
+        summaryKeys: ["path"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "write_file",
+                description: "Prefer this tool for creating new files or fully replacing existing ones. You MUST read an existing file with read_file before overwriting it. Prefer edit_file for modifying existing files -- it only sends the diff. Do not create documentation files (*.md, README) by default; only do so when explicitly asked or when documentation is clearly part of the requested change.",
+                parameters: {
+                    type: "object",
+                    properties: { path: { type: "string" }, content: { type: "string" } },
+                    required: ["path", "content"],
+                },
+            },
+        },
+        handler: (a) => {
+            const resolvedPath = resolveLocalToolPath(a.path);
+            fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+            fs.writeFileSync(resolvedPath, a.content, "utf-8");
+            (0, scrutiny_1.trackModifiedFile)(resolvedPath);
+            const scrutiny = (0, scrutiny_1.getPostImplementationScrutiny)((0, scrutiny_1.getModifiedFileCount)());
+            /* v8 ignore next -- scrutiny appendix branch depends on session-level file count @preserve */
+            return scrutiny ? `ok\n\n${scrutiny}` : "ok";
+        },
+        summaryKeys: ["path"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "edit_file",
+                description: "Surgically edit a file by replacing an exact string. The file MUST have been read via read_file first -- this tool will reject the call otherwise. old_string must match EXACTLY ONE location in the file -- if it matches zero or multiple, the edit fails. To fix: provide more surrounding context to make the match unique. Preserve exact indentation (tabs/spaces) from the file. Prefer this over write_file for modifications -- it only sends the diff.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string" },
+                        old_string: { type: "string" },
+                        new_string: { type: "string" },
+                    },
+                    required: ["path", "old_string", "new_string"],
+                },
+            },
+        },
+        handler: (a) => {
+            const resolvedPath = resolveLocalToolPath(a.path);
+            if (!tools_base_1.editFileReadTracker.has(resolvedPath)) {
+                return `error: you must read the file with read_file before editing it. call read_file on ${a.path} first.`;
+            }
+            // Check staleness before editing
+            const stalenessCheck = file_state_1.fileStateCache.isStale(resolvedPath);
+            let content;
+            try {
+                content = fs.readFileSync(resolvedPath, "utf-8");
+            }
+            catch (e) {
+                return `error: could not read file: ${e instanceof Error ? e.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(e)}`;
+            }
+            // Count occurrences
+            const occurrences = [];
+            let searchFrom = 0;
+            while (true) {
+                const idx = content.indexOf(a.old_string, searchFrom);
+                if (idx === -1)
+                    break;
+                occurrences.push(idx);
+                searchFrom = idx + 1;
+            }
+            if (occurrences.length === 0) {
+                return `error: old_string not found in ${a.path}`;
+            }
+            if (occurrences.length > 1) {
+                return `error: old_string is ambiguous -- found ${occurrences.length} matches in ${a.path}. provide more context to make the match unique.`;
+            }
+            // Single unique match -- replace
+            const idx = occurrences[0];
+            const updated = content.slice(0, idx) + a.new_string + content.slice(idx + a.old_string.length);
+            fs.writeFileSync(resolvedPath, updated, "utf-8");
+            // Update file state cache with new content
+            try {
+                const newMtime = fs.statSync(resolvedPath).mtimeMs;
+                file_state_1.fileStateCache.record(resolvedPath, updated, newMtime);
+            }
+            catch {
+                // stat failed -- skip cache update
+            }
+            // Build contextual diff
+            const lines = updated.split("\n");
+            const prefixLines = content.slice(0, idx).split("\n");
+            const changeStartLine = prefixLines.length - 1;
+            const newStringLines = a.new_string.split("\n");
+            const changeEndLine = changeStartLine + newStringLines.length;
+            const diffResult = buildContextDiff(lines, changeStartLine, changeEndLine);
+            // Track modified file and compute scrutiny appendix
+            (0, scrutiny_1.trackModifiedFile)(resolvedPath);
+            const scrutiny = (0, scrutiny_1.getPostImplementationScrutiny)((0, scrutiny_1.getModifiedFileCount)());
+            // Append staleness warning if detected (do not block -- TTFA)
+            /* v8 ignore start -- staleness+diff+scrutiny combo not exercised in integration tests @preserve */
+            if (stalenessCheck.stale) {
+                const base = `${diffResult}\n\n⚠️ warning: file changed externally since last read -- re-read recommended`;
+                return scrutiny ? `${base}\n\n${scrutiny}` : base;
+            }
+            /* v8 ignore stop */
+            /* v8 ignore next -- scrutiny appendix branch depends on session-level file count @preserve */
+            return scrutiny ? `${diffResult}\n\n${scrutiny}` : diffResult;
+        },
+        summaryKeys: ["path"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "glob",
+                description: "Find files matching a glob pattern, sorted alphabetically. Use this instead of shell commands like `find` or `ls`. For broad exploratory searches that would require multiple rounds of globbing and grepping, consider using claude or coding_spawn.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        pattern: { type: "string", description: "glob pattern (e.g. **/*.ts)" },
+                        cwd: { type: "string", description: "directory to search from (defaults to process.cwd())" },
+                    },
+                    required: ["pattern"],
+                },
+            },
+        },
+        handler: (a) => {
+            const cwd = a.cwd ? resolveLocalToolPath(a.cwd) : process.cwd();
+            const matches = fg.globSync(a.pattern, { cwd, dot: true });
+            return matches.sort().join("\n");
+        },
+        summaryKeys: ["pattern", "cwd"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "grep",
+                description: "Search file contents for lines matching a regex pattern. Searches recursively in directories. Use this instead of shell commands like `grep` or `rg`. Returns matching lines with file path and line numbers. Use context_lines for surrounding context. Use include to filter file types (e.g., '*.ts').",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        pattern: { type: "string", description: "regex pattern to search for" },
+                        path: { type: "string", description: "file or directory to search" },
+                        context_lines: { type: "number", description: "number of surrounding context lines (default 0)" },
+                        include: { type: "string", description: "glob filter to limit searched files (e.g. *.ts)" },
+                    },
+                    required: ["pattern", "path"],
+                },
+            },
+        },
+        handler: (a) => {
+            const targetPath = resolveLocalToolPath(a.path);
+            const regex = new RegExp(a.pattern);
+            const contextLines = parseInt(a.context_lines || "0", 10);
+            const includeGlob = a.include || undefined;
+            function searchFile(filePath) {
+                let content;
+                try {
+                    content = fs.readFileSync(filePath, "utf-8");
+                }
+                catch {
+                    return [];
+                }
+                const lines = content.split("\n");
+                const matchIndices = new Set();
+                for (let i = 0; i < lines.length; i++) {
+                    if (regex.test(lines[i])) {
+                        matchIndices.add(i);
+                    }
+                }
+                if (matchIndices.size === 0)
+                    return [];
+                const outputIndices = new Set();
+                for (const idx of matchIndices) {
+                    const start = Math.max(0, idx - contextLines);
+                    const end = Math.min(lines.length - 1, idx + contextLines);
+                    for (let i = start; i <= end; i++) {
+                        outputIndices.add(i);
+                    }
+                }
+                const sortedIndices = [...outputIndices].sort((a, b) => a - b);
+                const results = [];
+                for (const idx of sortedIndices) {
+                    const lineNum = idx + 1;
+                    if (matchIndices.has(idx)) {
+                        results.push(`${filePath}:${lineNum}: ${lines[idx]}`);
+                    }
+                    else {
+                        results.push(`-${filePath}:${lineNum}: ${lines[idx]}`);
+                    }
+                }
+                return results;
+            }
+            function collectFiles(dirPath) {
+                const files = [];
+                function walk(dir) {
+                    let entries;
+                    try {
+                        entries = fs.readdirSync(dir, { withFileTypes: true });
+                    }
+                    catch {
+                        return;
+                    }
+                    for (const entry of entries) {
+                        const fullPath = path.join(dir, entry.name);
+                        if (entry.isDirectory()) {
+                            walk(fullPath);
+                        }
+                        else if (entry.isFile()) {
+                            files.push(fullPath);
+                        }
+                    }
+                }
+                walk(dirPath);
+                return files.sort();
+            }
+            function matchesGlob(filePath, glob) {
+                const escaped = glob
+                    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+                    .replace(/\*/g, ".*")
+                    .replace(/\?/g, ".");
+                return new RegExp(`(^|/)${escaped}$`).test(filePath);
+            }
+            const stat = fs.statSync(targetPath, { throwIfNoEntry: false });
+            if (!stat)
+                return "";
+            if (stat.isFile()) {
+                return searchFile(targetPath).join("\n");
+            }
+            let files = collectFiles(targetPath);
+            if (includeGlob) {
+                files = files.filter((f) => matchesGlob(f, includeGlob));
+            }
+            const allResults = [];
+            for (const file of files) {
+                allResults.push(...searchFile(file));
+            }
+            return allResults.join("\n");
+        },
+        summaryKeys: ["pattern", "path", "include"],
+    },
+];

package/dist/repertoire/tools-flight.js

@@ -0,0 +1,224 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flightToolDefinitions = void 0;
+exports.resetDuffelClient = resetDuffelClient;
+const duffel_client_1 = require("./duffel-client");
+const user_profile_1 = require("./user-profile");
+const credential_access_1 = require("./credential-access");
+const runtime_1 = require("../nerves/runtime");
+// Lazy-initialized Duffel client singleton
+let _duffelClient = null;
+async function getDuffelClient() {
+    if (!_duffelClient) {
+        _duffelClient = await (0, duffel_client_1.createDuffelClient)();
+    }
+    return _duffelClient;
+}
+function requireFamilyContext(ctx) {
+    if (!ctx?.context?.friend?.id) {
+        return "no friend context — cannot access flight tools.";
+    }
+    if (ctx.context.friend.trustLevel !== "family") {
+        return "booking and cancellation require family trust level.";
+    }
+    return { friendId: ctx.context.friend.id };
+}
+function requireFriendContext(ctx) {
+    if (!ctx?.context?.friend?.id) {
+        return "no friend context — cannot search flights.";
+    }
+    return { friendId: ctx.context.friend.id };
+}
+exports.flightToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "flight_search",
+                description: "Search for flights between two airports. Returns available offers with prices.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        origin: { type: "string", description: "Origin airport IATA code (e.g. 'SFO')" },
+                        destination: { type: "string", description: "Destination airport IATA code (e.g. 'JFK')" },
+                        departure_date: { type: "string", description: "Departure date (YYYY-MM-DD)" },
+                        return_date: { type: "string", description: "Return date for round trips (optional)" },
+                        passengers: { type: "string", description: "Number of adult passengers (default '1')" },
+                        cabin_class: { type: "string", description: "Cabin class: economy, premium_economy, business, first" },
+                    },
+                    required: ["origin", "destination", "departure_date"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_flight_search",
+                message: "flight_search invoked",
+                meta: { tool: "flight_search", origin: args.origin, destination: args.destination },
+            });
+            const guard = requireFriendContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            try {
+                const client = await getDuffelClient();
+                const passengerCount = parseInt(args.passengers || "1", 10);
+                const passengers = Array.from({ length: passengerCount }, () => ({ type: "adult" }));
+                const offers = await client.searchFlights({
+                    origin: args.origin,
+                    destination: args.destination,
+                    departureDate: args.departure_date,
+                    returnDate: args.return_date,
+                    passengers,
+                    cabinClass: args.cabin_class,
+                });
+                if (offers.length === 0) {
+                    return "no flights found for those criteria.";
+                }
+                return JSON.stringify(offers, null, 2);
+            }
+            catch (err) {
+                /* v8 ignore next -- defensive @preserve */
+                return `flight search error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+        summaryKeys: ["origin", "destination", "departure_date"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "flight_hold",
+                description: "Hold a flight offer for a short period before committing to book. Not all airlines support holds.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        offer_id: { type: "string", description: "The Duffel offer ID to hold" },
+                    },
+                    required: ["offer_id"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_flight_hold",
+                message: "flight_hold invoked",
+                meta: { tool: "flight_hold", offerId: args.offer_id },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            // Hold functionality would call Duffel's offer hold API.
+            // For pre-build, we return a structured acknowledgment.
+            return JSON.stringify({
+                status: "hold_requested",
+                offerId: args.offer_id,
+                message: "Hold requested. Confirm or cancel before the hold expires.",
+            });
+        },
+        summaryKeys: ["offer_id"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "flight_book",
+                description: "Book a flight. Pulls passenger name/DOB/passport from the user's profile. Creates a virtual card, books the flight, then deactivates the card. Requires family trust level.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        offer_id: { type: "string", description: "The Duffel offer ID to book" },
+                        amount: { type: "string", description: "Expected total amount in dollars" },
+                        currency: { type: "string", description: "Currency code (e.g. 'usd')" },
+                    },
+                    required: ["offer_id", "amount", "currency"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_flight_book",
+                message: "flight_book invoked",
+                meta: { tool: "flight_book", offerId: args.offer_id },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            try {
+                const store = (0, credential_access_1.getCredentialStore)();
+                // Get passenger data from profile
+                const legalName = await (0, user_profile_1.getUserProfileField)(guard.friendId, "legalName", store);
+                if (!legalName) {
+                    return "passenger profile not found — please store your profile first using user_profile_store.";
+                }
+                const dateOfBirth = await (0, user_profile_1.getUserProfileField)(guard.friendId, "dateOfBirth", store);
+                const passport = await (0, user_profile_1.getUserProfileField)(guard.friendId, "passport", store);
+                const client = await getDuffelClient();
+                const result = await client.createOrder({
+                    offerId: args.offer_id,
+                    passengers: [{
+                            type: "adult",
+                            givenName: legalName.first,
+                            familyName: legalName.last,
+                            /* v8 ignore next -- reason @preserve */
+                            dateOfBirth: dateOfBirth ?? "1990-01-01",
+                            passportNumber: passport?.number,
+                            passportCountry: passport?.country,
+                            passportExpiry: passport?.expiry,
+                        }],
+                    amount: parseFloat(args.amount),
+                    currency: args.currency,
+                });
+                return JSON.stringify(result, null, 2);
+            }
+            catch (err) {
+                /* v8 ignore next -- defensive @preserve */
+                return `booking error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+        summaryKeys: ["offer_id", "amount"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "flight_cancel",
+                description: "Cancel a flight booking. Not all bookings are cancellable. Requires family trust level.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        order_id: { type: "string", description: "The Duffel order ID to cancel" },
+                    },
+                    required: ["order_id"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.tool_flight_cancel",
+                message: "flight_cancel invoked",
+                meta: { tool: "flight_cancel", orderId: args.order_id },
+            });
+            const guard = requireFamilyContext(ctx);
+            if (typeof guard === "string")
+                return guard;
+            try {
+                const client = await getDuffelClient();
+                const result = await client.cancelOrder(args.order_id);
+                return JSON.stringify(result, null, 2);
+            }
+            catch (err) {
+                /* v8 ignore next -- defensive @preserve */
+                return `cancellation error: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        },
+        summaryKeys: ["order_id"],
+    },
+];
+/** Reset the Duffel client singleton (for testing). */
+function resetDuffelClient() {
+    _duffelClient = null;
+}

package/dist/repertoire/tools-flow.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.restTool = exports.speakTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
+exports.ponderTool = {
+    type: "function",
+    function: {
+        name: "ponder",
+        description: "create or revise a typed ponder packet so i don't lose the plot while i keep working. use this for harness friction, research, or reflection that should survive the current turn. ponder does not end the turn, does not defer the response by itself, and may be followed by more tools before i settle or rest. Don't ponder trivial questions.",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["create", "revise"],
+                    description: "create a new packet or revise an existing drafting packet.",
+                },
+                kind: {
+                    type: "string",
+                    enum: ["harness_friction", "research", "reflection"],
+                    description: "the packet kind. determines the SOP the inner session should follow.",
+                },
+                packet_id: {
+                    type: "string",
+                    description: "required for action=revise. the packet to revise in place.",
+                },
+                follows_packet_id: {
+                    type: "string",
+                    description: "optional follow-up linkage when a new packet grows out of an earlier one.",
+                },
+                objective: {
+                    type: "string",
+                    description: "the durable objective for this packet.",
+                },
+                summary: {
+                    type: "string",
+                    description: "brief factual summary of the work object or friction being preserved.",
+                },
+                success_criteria: {
+                    type: "string",
+                    description: "newline-delimited success criteria bullets.",
+                },
+                payload_json: {
+                    type: "string",
+                    description: "JSON object string with packet-specific structured details. use {} when empty.",
+                },
+                thought: {
+                    type: "string",
+                    description: "deprecated compatibility field. legacy thought text is normalized into a reflection packet.",
+                },
+                say: {
+                    type: "string",
+                    description: "deprecated compatibility field. retained for migration only; it no longer controls deferral or silence.",
+                },
+            },
+        },
+    },
+};
+exports.observeTool = {
+    type: "function",
+    function: {
+        name: "observe",
+        description: "absorb what happened without responding — the moment doesn't call for words. must be the only tool call in the turn.",
+        parameters: {
+            type: "object",
+            properties: {
+                reason: { type: "string", description: "brief reason for staying silent (for logging)" },
+            },
+        },
+    },
+};
+exports.settleTool = {
+    type: "function",
+    function: {
+        name: "settle",
+        description: "deliver your response and end your turn — this hands control back to the user. only settle when your work is complete, you're genuinely blocked, or the user asked a direct question that needs an answer now. do not settle with status updates mid-task. if you're settling with 'I'll look into that,' you probably should be using a tool instead.",
+        parameters: {
+            type: "object",
+            properties: {
+                answer: { type: "string" },
+                intent: { type: "string", enum: ["complete", "blocked", "direct_reply"] },
+            },
+            required: ["answer"],
+        },
+    },
+};
+exports.speakTool = {
+    type: "function",
+    function: {
+        name: "speak",
+        description: "i speak to send words to my friend mid-turn without ending it. for progress, acknowledgment, or phase-boundary updates during heavy work. i settle when my work is done or i need a reply. speak is one-way: my friend cannot steer me mid-turn after i speak.",
+        parameters: {
+            type: "object",
+            properties: {
+                message: { type: "string", description: "the words i'm sending to my friend right now" },
+            },
+            required: ["message"],
+        },
+    },
+};
+exports.restTool = {
+    type: "function",
+    function: {
+        name: "rest",
+        description: "end an inner-session turn when i'm done thinking. rest remains the explicit terminal move for the inner session and must be the only tool call in the turn. on idle heartbeat turns, use status=HEARTBEAT_OK.",
+        parameters: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    description: "optional rest status. use HEARTBEAT_OK when the heartbeat fires and there is nothing to do.",
+                },
+                note: {
+                    type: "string",
+                    description: "optional brief note about why i'm resting.",
+                },
+            },
+        },
+    },
+};