lifeos__read_pending_queue

Instructions

Implementation Reference

• src/tools/read_pending_queue.ts:13-93 (handler)

  The main handler function that registers and implements lifeos__read_pending_queue. It queries the EdgeStore for edges in 'proposed' review state, optionally filtered by 'since' ISO timestamp and 'limit' (default 50, max 200). Returns shaped edge data including src/dst paths, type, strength, confidence, rationale, citations, etc. Handles empty queue and EdgeStore-unavailable errors gracefully.

  export function registerReadPendingQueueTool(
    server: McpServer,
    _ctx: LifeOSContext
  ): void {
    server.tool(
      TOOL_NAME,
      "List proposed edges waiting in the LifeOS Curator inbox. Read-only — no write opt-in required. Use since and limit to paginate.",
      {
        since: z
          .string()
          .optional()
          .describe(
            "ISO-8601 timestamp — return only edges queued after this time. Omit for all pending."
          ),
        limit: z
          .number()
          .int()
          .min(1)
          .max(200)
          .optional()
          .describe("Max edges to return (default 50, max 200)"),
      },
      async ({ since, limit }) => {
        try {
          const store = getEdgeStore();
          const edges = store.pendingQueue(since, limit ?? 50);
  
          if (edges.length === 0) {
            const empty = {
              count: 0,
              edges: [],
              message: "No proposed edges in the queue.",
            };
            return {
              content: [{ type: "text" as const, text: JSON.stringify(empty, null, 2) }],
            };
          }
  
          // Shape the output for the MCP client — include rationale from mcpMetadata.
          const items = edges.map((e) => ({
            edge_id: e.id,
            src: e.srcAnchor ? `${e.srcPath}#${e.srcAnchor}` : e.srcPath,
            dst: e.dstAnchor ? `${e.dstPath}#${e.dstAnchor}` : e.dstPath,
            type: e.type,
            strength: e.strength,
            confidence: e.confidence,
            queued_since: e.queuedSince,
            formed_date: e.formedDate,
            rationale: e.mcpMetadata?.rationale ?? null,
            speculative: e.mcpMetadata?.speculative ?? false,
            citations: e.citations.map((c) => ({
              path: c.nodePath,
              quote: c.quote,
            })),
          }));
  
          const result = {
            count: items.length,
            edges: items,
            has_more: items.length === (limit ?? 50),
          };
  
          return {
            content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          // EdgeStore may not exist yet (Cadence app never run).
          const msg = err instanceof Error ? err.message : String(err);
          const dbErr = {
            count: 0,
            edges: [],
            error: "edge-store-unavailable",
            detail: `Could not open EdgeStore: ${msg}`,
          };
          return {
            content: [{ type: "text" as const, text: JSON.stringify(dbErr, null, 2) }],
          };
        }
      }
    );
  }

• src/tools/read_pending_queue.ts:20-34 (schema)

  Zod input schema for lifeos__read_pending_queue. Defines optional 'since' (ISO-8601 string) and 'limit' (integer 1-200, default 50) parameters.

  {
    since: z
      .string()
      .optional()
      .describe(
        "ISO-8601 timestamp — return only edges queued after this time. Omit for all pending."
      ),
    limit: z
      .number()
      .int()
      .min(1)
      .max(200)
      .optional()
      .describe("Max edges to return (default 50, max 200)"),
  },

• src/server/index.ts:41-42 (registration)

  Registration of the tool in the MCP server. The tool is always registered regardless of write-opt-in status, as noted by the comment 'lifeos__read_pending_queue is always accessible (no opt-in)'.

  // lifeos__read_pending_queue is always accessible (no opt-in)
  registerReadPendingQueueTool(server, ctx);

• src/lib/ts-edge-store.ts:192-220 (helper)

  The pendingQueue method in TsEdgeStore that executes the SQL query against SQLite. Queries edges with review_state='proposed', ordered by formed_date DESC (or queued_since > :since if provided), with a LIMIT clause. This is the data access layer backing the tool.

  /**
   * Returns proposed edges, newest first.
   * If `since` is provided, returns only edges queued after that ISO timestamp.
   */
  pendingQueue(since?: string, limit: number = 50): Edge[] {
    if (since) {
      const rows = this.db
        .prepare(
          `SELECT * FROM edges
           WHERE review_state = 'proposed'
             AND queued_since > :since
           ORDER BY queued_since DESC
           LIMIT :limit`
        )
        .all({ since, limit }) as unknown as RawEdgeRow[];
      return rows.map(rowToEdge);
    } else {
      const rows = this.db
        .prepare(
          `SELECT * FROM edges
           WHERE review_state = 'proposed'
           ORDER BY formed_date DESC
           LIMIT :limit`
        )
        .all({ limit }) as unknown as RawEdgeRow[];
      return rows.map(rowToEdge);
    }
  }

• src/config.ts:43-44 (registration)

  Config-level declaration that lifeos__read_pending_queue is a READ_ONLY_TOOL, always accessible without opt-in. Listed alongside WRITE_TOOL_NAMES in the health check.

  /** lifeos__read_pending_queue is always accessible — no opt-in required. */
  export const READ_ONLY_TOOLS = ["lifeos__read_pending_queue"] as const;