Cantrip

Instructions

Implementation Reference

• src/tools.ts:408-411 (handler)

  Handler function for cantrip_history tool - resolves project context and calls client.post('history') with filter flags (type, entity, since, limit) and project

  handler: async (p) => {
    const project = resolveProject(p.project as string | undefined);
    return client.post("history", [], { ...buildFlags({ type: p.type, entity: p.entity, since: p.since, limit: p.limit }), project });
  },

• src/tools.ts:399-407 (schema)

  Input schema/shape for cantrip_history tool - defines optional filters: type (event type), entity, since (ISO date), limit (max events), and project

    type: z
      .string()
      .optional()
      .describe("Filter by event type (e.g. init, entity_created, review_accept)"),
    entity: z.string().optional().describe("Filter by entity type (e.g. icp, pain_point)"),
    since: z.string().optional().describe("Only events after this ISO date"),
    limit: z.number().optional().describe("Max events to return (default: 50)"),
    project: projectSchema,
  },

• src/tools.ts:393-412 (registration)

  Full tool registration for cantrip_history - registers tool name, description, input shape, and handler function

  {
    name: "cantrip_history",
    description:
      "Query the append-only audit trail of all actions taken on the project." +
      PROJECT_DESC_SUFFIX,
    shape: {
      type: z
        .string()
        .optional()
        .describe("Filter by event type (e.g. init, entity_created, review_accept)"),
      entity: z.string().optional().describe("Filter by entity type (e.g. icp, pain_point)"),
      since: z.string().optional().describe("Only events after this ISO date"),
      limit: z.number().optional().describe("Max events to return (default: 50)"),
      project: projectSchema,
    },
    handler: async (p) => {
      const project = resolveProject(p.project as string | undefined);
      return client.post("history", [], { ...buildFlags({ type: p.type, entity: p.entity, since: p.since, limit: p.limit }), project });
    },
  },

• src/tools.ts:27-35 (helper)

  buildFlags helper function - converts parameter object to flags record, filtering out undefined/null/empty values, used by cantrip_history handler

  function buildFlags(params: Record<string, unknown>): Record<string, string> {
    const flags: Record<string, string> = {};
    for (const [k, v] of Object.entries(params)) {
      if (v !== undefined && v !== null && v !== "") {
        flags[k] = String(v);
      }
    }
    return flags;
  }

• src/client.ts:36-46 (helper)

  resolveProject helper function - resolves project context from inline slug or .cantrip.json file, throws error if neither available

  export function resolveProject(inlineSlug?: string): string {
    if (inlineSlug) return inlineSlug;
  
    const fromFile = readProjectContext();
    if (fromFile) return fromFile;
  
    throw new Error(
      "No project context. Either pass the 'project' slug as a parameter, " +
      "or run cantrip_connect first.",
    );
  }