board_log_activity

Instructions

Implementation Reference

• src/tools/activity.ts:32-59 (handler)

  The handler function for board_log_activity. Writes an entry to the 'activity_log' Firestore collection with agent_name, action, details, task_id, session_id, metadata, and a created_at timestamp. Returns the document id, action, and a success message.

  async ({ agent_name, action, details, task_id, session_id, metadata }) => {
    const docRef = await db.collection("activity_log").add({
      task_id: task_id ?? null,
      session_id: session_id ?? null,
      agent_name,
      action,
      details: details ?? null,
      metadata: metadata ?? {},
      created_at: Timestamp.now(),
    });
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              id: docRef.id,
              action,
              message: "Activity logged successfully",
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/activity.ts:9-31 (schema)

  Zod schema defining the input parameters for board_log_activity: agent_name (string, required), action (enum of 9 values, required), details (optional string), task_id (optional string), session_id (optional string), metadata (optional record).

  {
    agent_name: z.string().describe("Name of the agent (free-form string — e.g., 'main', 'code-reviewer', 'gcp-infra'). Used for filtering and audit."),
    action: z
      .enum([
        "created",
        "updated",
        "claimed",
        "blocked",
        "completed",
        "commented",
        "mode_changed",
        "session_started",
        "session_ended",
      ])
      .describe("Action type. Fixed enum. Most values correspond to lifecycle events written automatically by other tools; use 'commented' for free-form notes/observations logged manually."),
    details: z.string().optional().describe("Human-readable description of what happened. Required in practice for 'commented' — without it, the entry is empty."),
    task_id: z.string().optional().describe("Related task ID if this activity is about a specific task. Enables filtering via board_get_activity(task_id=...). Omit for project-level or session-level events."),
    session_id: z.string().optional().describe("Related session ID if this activity is scoped to a specific session. Enables filtering via board_get_activity(session_id=...)."),
    metadata: z
      .record(z.string(), z.unknown())
      .optional()
      .describe("Optional structured payload (e.g., { commit_sha: 'abc123', build_id: 'build-456' }). Stored verbatim, not indexed."),
  },

• src/tools/activity.ts:6-60 (registration)

  Registration of board_log_activity via server.tool() in the registerActivityTools function. Called from src/index.ts line 31.

  server.tool(
    "board_log_activity",
    "Append an entry to the activity_log — a write-only audit stream of what agents did, decided, or observed. Use this for: RESEARCH observations the next session should see, decisions made during PLAN/REVIEW, blockers, notable failures, or any context that shouldn't be lost. Most status/assignment changes via board_update_task and board_create_task already write their own activity_log entries automatically — call this explicitly for free-form comments (action='commented') or arbitrary actions. Read back via board_get_activity. Returns { id, action, message }.",
    {
      agent_name: z.string().describe("Name of the agent (free-form string — e.g., 'main', 'code-reviewer', 'gcp-infra'). Used for filtering and audit."),
      action: z
        .enum([
          "created",
          "updated",
          "claimed",
          "blocked",
          "completed",
          "commented",
          "mode_changed",
          "session_started",
          "session_ended",
        ])
        .describe("Action type. Fixed enum. Most values correspond to lifecycle events written automatically by other tools; use 'commented' for free-form notes/observations logged manually."),
      details: z.string().optional().describe("Human-readable description of what happened. Required in practice for 'commented' — without it, the entry is empty."),
      task_id: z.string().optional().describe("Related task ID if this activity is about a specific task. Enables filtering via board_get_activity(task_id=...). Omit for project-level or session-level events."),
      session_id: z.string().optional().describe("Related session ID if this activity is scoped to a specific session. Enables filtering via board_get_activity(session_id=...)."),
      metadata: z
        .record(z.string(), z.unknown())
        .optional()
        .describe("Optional structured payload (e.g., { commit_sha: 'abc123', build_id: 'build-456' }). Stored verbatim, not indexed."),
    },
    async ({ agent_name, action, details, task_id, session_id, metadata }) => {
      const docRef = await db.collection("activity_log").add({
        task_id: task_id ?? null,
        session_id: session_id ?? null,
        agent_name,
        action,
        details: details ?? null,
        metadata: metadata ?? {},
        created_at: Timestamp.now(),
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(
              {
                id: docRef.id,
                action,
                message: "Activity logged successfully",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/types.ts:57-74 (helper)

  The ActivityLog interface in src/types.ts defines the data shape stored in Firestore, matching the tool's schema and handler output.

  export interface ActivityLog {
    task_id: string | null;
    session_id: string | null;
    agent_name: string;
    action:
      | "created"
      | "updated"
      | "claimed"
      | "blocked"
      | "completed"
      | "commented"
      | "mode_changed"
      | "session_started"
      | "session_ended";
    details: string | null;
    metadata: Record<string, unknown>;
    created_at: Timestamp;
  }