Function createCtxNoteTool

packages/plugin/src/tools/ctx-note/tools.ts:164–336

(deps: CtxNoteToolDeps)

}

function createCtxNoteTool(deps: CtxNoteToolDeps): ToolDefinition {
    return tool({
        description: CTX_NOTE_DESCRIPTION,
        args: {
            action: tool.schema
                .enum(["write", "read", "dismiss", "update"])
                .optional()
                .describe(
                    "Operation to perform. Defaults to 'write' when content is provided, otherwise 'read'.",
                ),
            content: tool.schema
                .string()
                .optional()
                .describe("Note text to store when action is 'write'."),
            surface_condition: tool.schema
                .string()
                .optional()
                .describe(
                    "Externally verifiable condition for smart notes. A separate background agent (dreamer) checks this using gh CLI, web fetches, file reads, git, etc. — NOT your conversation history. Use only for things like GitHub PR/issue state, release tags, file contents, or workflow runs. DO NOT use for 'when the user mentions X' / 'when we revisit Y' / 'when relevant to current task' — dreamer has no access to session context. For session-relative reminders, omit this and write a regular note.",
                ),
            filter: tool.schema
                .enum(["all", "active", "pending", "ready", "dismissed"])
                .optional()
                .describe(
                    "Optional read filter. Defaults to active session notes + ready smart notes. Use 'all' to inspect every status or 'pending' to inspect unsurfaced smart notes.",
                ),
            limit: tool.schema
                .number()
                .optional()
                .describe("Max notes per section for read, newest first (default: 25)"),
            offset: tool.schema
                .number()
                .optional()
                .describe("Skip this many newest notes for read — page older ones (default: 0)"),
            note_id: tool.schema
                .number()
                .optional()
                .describe("Note ID (required for 'dismiss' and 'update' actions)."),
        },
        async execute(args: CtxNoteArgs, toolContext) {
            const sessionId = toolContext.sessionID;
            // Infer write only on NON-EMPTY content. GPT-family models fill every
            // optional param (content:"" for a read), so a bare `typeof === "string"`
            // check would mis-infer `write` and then reject the empty content.
            const action = args.action ?? (args.content?.trim() ? "write" : "read");

            // Resolve the session's actual project from `toolContext.directory`
            // each call. OpenCode's top-level `ctx.directory` (the launch dir)
            // can differ from the session's working directory when the user
            // runs `opencode -s <id>` from outside the project.
            const projectIdentity = deps.resolveProjectPath?.(toolContext.directory);

            if (action === "write") {
                const content = args.content?.trim();
                if (!content) {
                    return "Error: 'content' is required when action is 'write'.";
                }