Give Ask a new tool

Ask is what answers when you message Pepper a question. It works with tools: ways to look things up on your Mac. A part (your own folder in src/parts/, see Make Pepper yours) can add one. This books part lets Ask look up the books people have recommended to you, from Pepper's facts table.

import { z } from "zod";
import { db } from "../../store/db.js";
import type { Part } from "../contract.js";

export const part: Part = {
  name: "books",
  about: "lets Ask look up the books people mention",
  tools: [{
    name: "search",
    description: "Books people have recommended to the owner. Filter by a word in the title.",
    input: z.object({ word: z.string().max(80) }),
    run: ({ word }) => JSON.stringify(db.prepare("SELECT value FROM facts WHERE predicate='recommended_book' AND value LIKE ? LIMIT 20").all(`%${String(word)}%`)),
  }],
};

Save it as src/parts/books/index.ts and add books: () => import("./books/index.js"), to src/parts/mine.ts. The model behind Ask sees the tool as books_search: the part's name, then the tool's name.

The facts come from the model, which names each one in its own words, so recommended_book is only an example: look at what Pepper actually called a book mention and use that name. The query also searches facts you haven't approved yet; add AND status='active' to search only the ones you have.

Pepper protects what a tool returns, even if the part's code does nothing about it. It wraps the result as untrusted text, so the model treats it as quoted data and not as instructions. It masks one-time codes and links that carry a secret, and nothing else, so never return a password or an API key. It limits the size to about 6000 characters, and a bigger result is dropped entirely, which is why the query has a LIMIT. If a tool throws an error, the error's message is passed to the model without the wrapping, so keep error messages short and free of anything from a message. A tool reads; it never sends or changes anything outside Pepper.