@tpsdev-ai/flair-mcp 0.20.1 → 0.22.0

package/dist/index.d.ts

@@ -8,12 +8,20 @@
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
  *   - memory_get     — retrieve a specific memory by ID
  *   - memory_delete  — delete a memory
+ *   - relationship_store — assert a subject/predicate/object relationship triple
  *   - bootstrap      — cold-start context (soul + recent memories)
  *   - soul_set       — set a personality/context entry
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
  *
+ * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
+ * rate-limited `POST /Presence` heartbeat for the calling agent (see
+ * ./presence.ts + the `heartbeat()` closure in runMcp()) — presence is now a
+ * side effect of normal activity instead of the manual `flair presence set`
+ * CLI command nobody ran. `bootstrap` additionally seeds the activity/task
+ * from its own arguments (session start signal).
+ *
  * Usage:
  *   npx -y @tpsdev-ai/flair-mcp
  *

package/dist/index.js

@@ -8,12 +8,20 @@
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
  *   - memory_get     — retrieve a specific memory by ID
  *   - memory_delete  — delete a memory
+ *   - relationship_store — assert a subject/predicate/object relationship triple
  *   - bootstrap      — cold-start context (soul + recent memories)
  *   - soul_set       — set a personality/context entry
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
  *
+ * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
+ * rate-limited `POST /Presence` heartbeat for the calling agent (see
+ * ./presence.ts + the `heartbeat()` closure in runMcp()) — presence is now a
+ * side effect of normal activity instead of the manual `flair presence set`
+ * CLI command nobody ran. `bootstrap` additionally seeds the activity/task
+ * from its own arguments (session start signal).
+ *
  * Usage:
  *   npx -y @tpsdev-ai/flair-mcp
  *
@@ -34,6 +42,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { FlairClient, FlairError } from "@tpsdev-ai/flair-client";
 import { z } from "zod";
+import { deriveActivity, postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
 // ─── Error helpers ──────────────────────────────────────────────────────────
 function classifyError(err, flairUrl) {
     if (err instanceof FlairError) {
@@ -138,6 +147,56 @@ export async function runMcp() {
         url: process.env.FLAIR_URL,
         keyPath: process.env.FLAIR_KEY_PATH,
     });
+    // ─── Auto-presence (flair#598) ────────────────────────────────────────────────
+    //
+    // Presence used to be manual-only (`flair presence set`, which in practice
+    // nobody runs) — so the roster was permanently stale and the collision-
+    // detection it exists for never worked. This makes presence a SIDE EFFECT of
+    // normal agent activity instead: `bootstrap` (session start) always attempts
+    // a heartbeat, and every other tool call attempts one too, both routed
+    // through the SAME rate-limited, fire-and-forget `heartbeat()` below so
+    // repeated bootstrap calls in a short window don't spam any more than
+    // repeated tool calls would.
+    //
+    // A SEPARATE FlairClient instance, not the main `flair` above — its own
+    // short `timeoutMs` (resolvePresenceTimeoutMs(), default 3s vs the main
+    // client's general-purpose 30s default) means a dead/slow daemon can never
+    // make a presence write outlive the tool call it rode in on, independent of
+    // whatever timeout the main client is configured with.
+    const presenceFlair = new FlairClient({
+        agentId,
+        url: process.env.FLAIR_URL,
+        keyPath: process.env.FLAIR_KEY_PATH,
+        timeoutMs: resolvePresenceTimeoutMs(),
+    });
+    // Rate-limit clock + last-known task, in-process only (no persistence —
+    // resets on restart, which is fine; the next tool call re-establishes it).
+    // Owned here, not in presence.ts, so the pure rate-limit/body-building logic
+    // stays testable without any shared mutable state.
+    let lastPresenceSentAt = null;
+    // currentTask is the caller's responsibility to preserve (see
+    // postPresenceSafe's doc comment): Presence.post() treats an ABSENT
+    // currentTask as an explicit clear, so a heartbeat that doesn't know about
+    // an in-flight task must keep resending the last one bootstrap() told us
+    // about, or it would silently erase it every ~3 minutes.
+    let lastKnownTask;
+    /**
+     * Fire-and-forget, rate-limited presence heartbeat. Safe to call from every
+     * tool handler unconditionally — the rate limit + postPresenceSafe's
+     * internal catch-everything mean this NEVER throws, NEVER awaits network
+     * I/O in the caller's path, and NEVER delays the tool response. The
+     * `.catch(() => {})` below is belt-and-suspenders (postPresenceSafe already
+     * never rejects) purely so a future change to that function can't
+     * accidentally reintroduce an unhandled rejection here.
+     */
+    function heartbeat(activity = "coding") {
+        const now = Date.now();
+        if (!shouldSendHeartbeat(now, lastPresenceSentAt, resolveHeartbeatIntervalMs()))
+            return;
+        lastPresenceSentAt = now; // set synchronously, before the async write, so a burst of
+        // tool calls in the same tick can't all slip past the rate limit together
+        postPresenceSafe(presenceFlair, activity, lastKnownTask, resolvePresenceTimeoutMs()).catch(() => { });
+    }
     // ─── MCP Server ──────────────────────────────────────────────────────────────
     const server = new McpServer({
         name: "flair",
@@ -148,6 +207,7 @@ export async function runMcp() {
         query: z.string().describe("Search query — natural language, semantic matching"),
         limit: z.coerce.number().optional().default(5).describe("Max results (default 5)"),
     }, async ({ query, limit }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const results = await flair.memory.search(query, { limit });
             if (results.length === 0) {
@@ -181,6 +241,7 @@ export async function runMcp() {
             "private -- never visible to another agent, even one with a memory grant. " +
             "shared -- visible to the owner and any agent holding a read/search grant."),
     }, async ({ content, type, durability, tags, visibility }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const result = await flair.memory.write(content, {
                 type: type,
@@ -233,6 +294,7 @@ export async function runMcp() {
         preserveHistory: z.coerce.boolean().optional().default(false)
             .describe("Write a new supersedes-linked version instead of overwriting in place (default false)"),
     }, async ({ id, content, preserveHistory }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const result = await flair.memory.update(id, content, { preserveHistory });
             const text = preserveHistory
@@ -250,6 +312,7 @@ export async function runMcp() {
     server.tool("memory_get", "Retrieve a specific memory by ID.", {
         id: z.string().describe("Memory ID"),
     }, async ({ id }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const mem = await flair.memory.get(id);
             if (!mem)
@@ -263,6 +326,7 @@ export async function runMcp() {
     server.tool("memory_delete", "Delete a memory by ID.", {
         id: z.string().describe("Memory ID to delete"),
     }, async ({ id }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             await flair.memory.delete(id);
             return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
@@ -271,6 +335,41 @@ export async function runMcp() {
             return errorResult(err, flair.url);
         }
     });
+    server.tool("relationship_store", "Record that <subject> <predicate> <object> — an explicit entity-to-entity relationship triple " +
+        "(e.g. 'nathan manages flair', 'flint reviews cli'), distinct from a free-text memory. " +
+        "ASSERT/UPSERT semantics: writing the SAME triple again (same subject/predicate/object) updates the " +
+        "existing row in place (confidence/validTo/source refresh) rather than creating a duplicate — safe to " +
+        "re-assert. Predicate is free text (no fixed enum) but prefer a small, consistent vocabulary so the graph " +
+        "stays queryable: manages, works_on, reviews, depends_on, replaces, owns, reports_to, advises. " +
+        "TO CONTRADICT a prior relationship: (a) re-asserting the identical triple just updates it — fine. " +
+        "(b) changing validTo on the SAME subject/predicate/object overwrites the old validTo (the graph tracks " +
+        "current state, not full history). (c) changing the PREDICATE (e.g. 'nathan manages flair' -> 'nathan " +
+        "advises flair') creates a SEPARATE relationship — it does NOT automatically close the old one. Close it " +
+        "yourself first: re-assert the OLD triple with a validTo set to now (or call relationship's delete), THEN " +
+        "store the new one.", {
+        subject: z.string().describe("Source entity — a person, project, or service (e.g. 'nathan')"),
+        predicate: z.string().describe("Relationship type, free text. Recommended vocabulary: manages, works_on, reviews, depends_on, " +
+            "replaces, owns, reports_to, advises — consistency helps recall, but any short verb phrase works."),
+        object: z.string().describe("Target entity — a person, project, or service (e.g. 'flair')"),
+        confidence: z.coerce.number().optional().describe("0.0-1.0, how certain (default 1.0 = explicitly stated)"),
+        validFrom: z.string().optional().describe("ISO timestamp this relationship became true (default: now)"),
+        validTo: z.string().optional().describe("ISO timestamp this relationship ended. Leave unset for an active relationship; set it (via a re-assert " +
+            "of this SAME subject/predicate/object) to close out a relationship you're contradicting with a new predicate."),
+        source: z.string().optional().describe("Where this was learned from (a memory ID, conversation, etc.)"),
+    }, async ({ subject, predicate, object, confidence, validFrom, validTo, source }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
+        try {
+            const result = await flair.relationship.write({ subject, predicate, object, confidence, validFrom, validTo, source });
+            const confStr = confidence !== undefined ? ` (confidence: ${confidence})` : "";
+            return {
+                content: [{ type: "text", text: `Relationship recorded: ${subject} → ${predicate} → ${object}${confStr} (id: ${result.id})` }],
+                structuredContent: { id: result.id, subject, predicate, object, written: true },
+            };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
     server.tool("bootstrap", "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.", {
         maxTokens: z.coerce.number().optional().default(4000).describe("Max tokens in output"),
         currentTask: z.string().optional().describe("Current task description — enables semantic search for relevant memories"),
@@ -278,6 +377,16 @@ export async function runMcp() {
         surface: z.string().optional().describe("Surface name (tps-build, tps-review, cli-session) — narrows prediction"),
         subjects: z.array(z.string()).optional().describe("Entity names to preload context for (e.g., ['flair', 'auth'])"),
     }, async ({ maxTokens, currentTask, channel, surface, subjects }) => {
+        // auto-presence (flair#598) — SESSION START. bootstrap() already receives
+        // exactly the payload Presence wants: currentTask is what the agent is
+        // about to work on, channel/surface are what deriveActivity() uses to
+        // pick something more specific than the "coding" default. Routed through
+        // the SAME rate-limited heartbeat() as every other tool, so calling
+        // bootstrap twice in quick succession (session resume/compact) doesn't
+        // double-send — it's still "sets presence once" per session in practice.
+        if (currentTask)
+            lastKnownTask = currentTask;
+        heartbeat(deriveActivity({ channel, surface }));
         try {
             const result = await flair.bootstrap({ maxTokens, currentTask, channel, surface, subjects });
             if (!result.context) {
@@ -293,6 +402,7 @@ export async function runMcp() {
         key: z.string().describe("Entry key (e.g., 'role', 'standards', 'project')"),
         value: z.string().describe("Entry value — personality trait, project context, coding standards, etc."),
     }, async ({ key, value }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             await flair.soul.set(key, value);
             return { content: [{ type: "text", text: `Soul entry '${key}' set.` }] };
@@ -304,6 +414,7 @@ export async function runMcp() {
     server.tool("soul_get", "Get a personality or project context entry.", {
         key: z.string().describe("Entry key"),
     }, async ({ key }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             const entry = await flair.soul.get(key);
             if (!entry)
@@ -331,6 +442,7 @@ export async function runMcp() {
         phase: z.string().optional().describe("Current phase (e.g. design, implement, review)"),
         summary: z.string().optional().describe("Short summary of current workspace state"),
     }, async ({ ref, label, provider, task, phase, summary }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             // No agentId in body — the server attributes from the signed identity.
             const body = {
@@ -361,6 +473,7 @@ export async function runMcp() {
         scope: z.string().optional().describe("Scope of the event (e.g. an agent id, repo, or 'org')"),
         targets: z.array(z.string()).optional().describe("Recipient agent ids"),
     }, async ({ kind, summary, detail, scope, targets }) => {
+        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
         try {
             // No authorId in body — the server attributes from the signed identity.
             const body = { kind, summary };

package/dist/presence.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Auto-presence — shared, pure/testable logic behind flair#598.
+ *
+ * Presence (`POST /Presence`, resources/Presence.ts) only ever updated via the
+ * manual `flair presence set` CLI command, which in practice nobody runs — so
+ * the roster is permanently stale and the active/idle/offline derivation it
+ * powers (Office Space collision detection) never means anything. This module
+ * makes presence a SIDE EFFECT of normal agent activity instead: every flair-mcp
+ * tool call (and the flair-session-start hook) can call `postPresenceSafe()`
+ * to refresh the calling agent's own `lastHeartbeatAt`, rate-limited so it
+ * doesn't turn into a write storm.
+ *
+ * Everything here is a pure function or a single fire-and-forget async
+ * wrapper — no module-level mutable state lives in this file. The rate-limit
+ * clock (`lastSentAt`) and the "last known task" text are owned by each
+ * CALLER (flair-mcp/src/index.ts's runMcp() closure, session-start-hook.ts's
+ * per-invocation scope) — this file only decides "is it time yet" and "what
+ * does the POST body look like", so both call sites share ONE implementation
+ * of those decisions without sharing any actual state.
+ */
+/** Mirrors VALID_ACTIVITIES in resources/Presence.ts — keep in sync. */
+export type PresenceActivity = "coding" | "reviewing" | "planning" | "debugging" | "idle";
+/**
+ * Derive a presence `activity` from the SAME context signals the `bootstrap`
+ * tool and the SessionStart hook already receive (channel/surface) — no new
+ * inputs, no separate classifier call. Three narrow, name-based overrides for
+ * the surfaces that are unambiguous on their own; everything else (including
+ * no surface at all, e.g. the session-start hook) falls through to "coding",
+ * since an MCP tool call is, definitionally, an agent doing something — never
+ * "idle" (idle/offline are purely functions of elapsed time since the last
+ * heartbeat; see derivePresenceStatus() in resources/Presence.ts).
+ *
+ * "debug"/"investigat"/"incident" is checked FIRST, ahead of "review" and
+ * "plan" — an active incident investigation (flair#613: the flagship
+ * collision-detection use case) is the most unambiguous and highest-signal
+ * surface name an agent can report, and previously had no matching bucket at
+ * all, silently falling into "coding" (or "reviewing" if the surface also
+ * happened to contain that substring — e.g. "incident-review").
+ */
+export declare function deriveActivity(ctx?: {
+    surface?: string;
+    channel?: string;
+}): PresenceActivity;
+/**
+ * Pure "is it time to send another heartbeat" check. The caller owns the
+ * clock (`lastSentAt`) — this function has no memory of its own, which is
+ * what makes it trivially unit-testable (no fake timers, no module reset
+ * between tests).
+ */
+export declare function shouldSendHeartbeat(now: number, lastSentAt: number | null, minIntervalMs: number): boolean;
+/**
+ * Minimum gap between auto-presence POSTs triggered by MCP tool activity.
+ *
+ * 3 minutes: the issue's proposal asks for "once per few minutes" (2-5min).
+ * 3min sits in the middle of that range —
+ *   - frequent enough that an actively-used agent survives at least one
+ *     missed beat before crossing the 10-minute OFFLINE threshold
+ *     (offlineThresholdMs() in resources/Presence.ts, default 600_000ms) —
+ *     a dropped/delayed write doesn't flip the roster to offline;
+ *   - infrequent enough that a hot loop (e.g. memory_search called several
+ *     times a minute while an agent works through a task) doesn't turn every
+ *     tool call into a presence write — this is the rate limiter's whole job.
+ * Not tuned to the 90s ACTIVE threshold (idleThresholdMs(), default 90_000ms)
+ * — matching that would mean heartbeating roughly every other tool call,
+ * defeating the point of rate limiting. An agent that's genuinely active but
+ * calls flair-mcp tools less than once every ~3min will read as "idle" (not
+ * "offline") between heartbeats, which is the correct signal: idle already
+ * means "present but no recent activity", exactly this case.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS: number;
+/** Resolve the heartbeat rate-limit interval from env, clamped to a sane range
+ *  (same validate-don't-trust-`??` pattern as FLAIR_MCP_PARENT_POLL_MS /
+ *  FLAIR_HOOK_TIMEOUT_MS elsewhere in this package — an empty-string override
+ *  must not silently become `0` and defeat the rate limit). */
+export declare function resolveHeartbeatIntervalMs(): number;
+/**
+ * Per-write timeout for auto-presence POSTs. Deliberately much shorter than
+ * FlairClient's general-purpose default (30s, client.ts DEFAULT_TIMEOUT) —
+ * auto-presence is a side effect, never the reason a tool call or a session
+ * hook waits. A dead/slow Flair daemon must not hold anything open.
+ */
+export declare const DEFAULT_PRESENCE_TIMEOUT_MS = 3000;
+export declare function resolvePresenceTimeoutMs(): number;
+/**
+ * Build the POST /Presence body. Exported so tests can pin the exact shape.
+ * Never includes agentId — identity is attributed server-side from the
+ * Ed25519 signature on the request (Presence.post(), agent-auth.ts), exactly
+ * like flair_workspace_set / flair_orgevent in index.ts. currentTask is
+ * omitted (not sent as null/empty) when absent, so callers that don't know a
+ * task can still heartbeat without explicitly clearing one that was set
+ * earlier — see postPresenceSafe()'s doc comment for why that matters.
+ *
+ * Natural-presence: this body always carries `activity`, and the server stamps
+ * `activityUpdatedAt` (resources/Presence.ts, buildPresenceRecord) on any beat
+ * that asserts activity/task — so a working agent keeps activity fresh, and one
+ * that stops lets it decay to last-known automatically (no manual clear). A
+ * future liveness-only beat (this body without `activity`) would refresh
+ * lastHeartbeatAt without re-stamping activity — the server treats the two
+ * independently.
+ */
+export declare function buildPresenceBody(activity: PresenceActivity, currentTask?: string): Record<string, unknown>;
+/** Minimal surface a presence write needs from a Flair client — matches
+ *  FlairClient.request()'s shape exactly, so the real client satisfies this
+ *  with zero adapter code, and tests can inject a stub without a live server
+ *  or a real FlairClient instance. */
+export interface PresencePoster {
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}
+/**
+ * POST /Presence and NEVER throw or reject — every failure mode (timeout,
+ * network error, 401/403/500 from the server, a malformed response) is
+ * caught and swallowed here, in this one place, so every call site gets the
+ * guarantee for free instead of re-implementing it. Not awaiting the
+ * returned promise is what makes a call site "fire and forget"; the promise
+ * itself resolving-never-rejecting is what makes doing that safe (no
+ * unhandled rejection even if a caller forgets the `.catch()` belt-and-
+ * suspenders).
+ *
+ * currentTask is intentionally the caller's responsibility, not derived here:
+ * Presence.post() (resources/Presence.ts) treats an ABSENT currentTask as an
+ * explicit clear — `sanitizeCurrentTask(undefined)` returns `null`, which then
+ * overwrites any previously-set task on every merge. That's correct for the
+ * CLI (`flair presence set --activity X` with no `--task` IS an explicit "no
+ * task" statement) but wrong for an automatic heartbeat, which should never
+ * silently erase a task a human or bootstrap() set minutes earlier. Callers
+ * that want tasks preserved across heartbeats must track and re-pass the last
+ * known task themselves (see index.ts's `lastKnownTask` / session-start-hook's
+ * per-invocation scope) — this function just forwards whatever it's given.
+ */
+export declare function postPresenceSafe(poster: PresencePoster, activity: PresenceActivity, currentTask: string | undefined, timeoutMs: number): Promise<void>;

package/dist/presence.js

@@ -0,0 +1,179 @@
+/**
+ * Auto-presence — shared, pure/testable logic behind flair#598.
+ *
+ * Presence (`POST /Presence`, resources/Presence.ts) only ever updated via the
+ * manual `flair presence set` CLI command, which in practice nobody runs — so
+ * the roster is permanently stale and the active/idle/offline derivation it
+ * powers (Office Space collision detection) never means anything. This module
+ * makes presence a SIDE EFFECT of normal agent activity instead: every flair-mcp
+ * tool call (and the flair-session-start hook) can call `postPresenceSafe()`
+ * to refresh the calling agent's own `lastHeartbeatAt`, rate-limited so it
+ * doesn't turn into a write storm.
+ *
+ * Everything here is a pure function or a single fire-and-forget async
+ * wrapper — no module-level mutable state lives in this file. The rate-limit
+ * clock (`lastSentAt`) and the "last known task" text are owned by each
+ * CALLER (flair-mcp/src/index.ts's runMcp() closure, session-start-hook.ts's
+ * per-invocation scope) — this file only decides "is it time yet" and "what
+ * does the POST body look like", so both call sites share ONE implementation
+ * of those decisions without sharing any actual state.
+ */
+/**
+ * Derive a presence `activity` from the SAME context signals the `bootstrap`
+ * tool and the SessionStart hook already receive (channel/surface) — no new
+ * inputs, no separate classifier call. Three narrow, name-based overrides for
+ * the surfaces that are unambiguous on their own; everything else (including
+ * no surface at all, e.g. the session-start hook) falls through to "coding",
+ * since an MCP tool call is, definitionally, an agent doing something — never
+ * "idle" (idle/offline are purely functions of elapsed time since the last
+ * heartbeat; see derivePresenceStatus() in resources/Presence.ts).
+ *
+ * "debug"/"investigat"/"incident" is checked FIRST, ahead of "review" and
+ * "plan" — an active incident investigation (flair#613: the flagship
+ * collision-detection use case) is the most unambiguous and highest-signal
+ * surface name an agent can report, and previously had no matching bucket at
+ * all, silently falling into "coding" (or "reviewing" if the surface also
+ * happened to contain that substring — e.g. "incident-review").
+ */
+export function deriveActivity(ctx = {}) {
+    const surface = (ctx.surface ?? "").toLowerCase();
+    if (surface.includes("debug") || surface.includes("investigat") || surface.includes("incident"))
+        return "debugging";
+    if (surface.includes("review"))
+        return "reviewing";
+    if (surface.includes("plan") || surface.includes("spec") || surface.includes("design"))
+        return "planning";
+    return "coding";
+}
+// ─── Rate limiting ──────────────────────────────────────────────────────────
+/**
+ * Pure "is it time to send another heartbeat" check. The caller owns the
+ * clock (`lastSentAt`) — this function has no memory of its own, which is
+ * what makes it trivially unit-testable (no fake timers, no module reset
+ * between tests).
+ */
+export function shouldSendHeartbeat(now, lastSentAt, minIntervalMs) {
+    if (lastSentAt == null)
+        return true;
+    return now - lastSentAt >= minIntervalMs;
+}
+/**
+ * Minimum gap between auto-presence POSTs triggered by MCP tool activity.
+ *
+ * 3 minutes: the issue's proposal asks for "once per few minutes" (2-5min).
+ * 3min sits in the middle of that range —
+ *   - frequent enough that an actively-used agent survives at least one
+ *     missed beat before crossing the 10-minute OFFLINE threshold
+ *     (offlineThresholdMs() in resources/Presence.ts, default 600_000ms) —
+ *     a dropped/delayed write doesn't flip the roster to offline;
+ *   - infrequent enough that a hot loop (e.g. memory_search called several
+ *     times a minute while an agent works through a task) doesn't turn every
+ *     tool call into a presence write — this is the rate limiter's whole job.
+ * Not tuned to the 90s ACTIVE threshold (idleThresholdMs(), default 90_000ms)
+ * — matching that would mean heartbeating roughly every other tool call,
+ * defeating the point of rate limiting. An agent that's genuinely active but
+ * calls flair-mcp tools less than once every ~3min will read as "idle" (not
+ * "offline") between heartbeats, which is the correct signal: idle already
+ * means "present but no recent activity", exactly this case.
+ */
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 3 * 60 * 1000;
+const HEARTBEAT_INTERVAL_FLOOR_MS = 30_000;
+const HEARTBEAT_INTERVAL_CEILING_MS = 15 * 60 * 1000;
+/** Resolve the heartbeat rate-limit interval from env, clamped to a sane range
+ *  (same validate-don't-trust-`??` pattern as FLAIR_MCP_PARENT_POLL_MS /
+ *  FLAIR_HOOK_TIMEOUT_MS elsewhere in this package — an empty-string override
+ *  must not silently become `0` and defeat the rate limit). */
+export function resolveHeartbeatIntervalMs() {
+    const raw = process.env.FLAIR_PRESENCE_HEARTBEAT_MS;
+    const parsed = raw != null ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed >= HEARTBEAT_INTERVAL_FLOOR_MS && parsed <= HEARTBEAT_INTERVAL_CEILING_MS
+        ? parsed
+        : DEFAULT_HEARTBEAT_INTERVAL_MS;
+}
+// ─── Timeout ────────────────────────────────────────────────────────────────
+/**
+ * Per-write timeout for auto-presence POSTs. Deliberately much shorter than
+ * FlairClient's general-purpose default (30s, client.ts DEFAULT_TIMEOUT) —
+ * auto-presence is a side effect, never the reason a tool call or a session
+ * hook waits. A dead/slow Flair daemon must not hold anything open.
+ */
+export const DEFAULT_PRESENCE_TIMEOUT_MS = 3_000;
+const PRESENCE_TIMEOUT_FLOOR_MS = 500;
+const PRESENCE_TIMEOUT_CEILING_MS = 10_000;
+export function resolvePresenceTimeoutMs() {
+    const raw = process.env.FLAIR_PRESENCE_TIMEOUT_MS;
+    const parsed = raw != null ? Number(raw) : NaN;
+    return Number.isFinite(parsed) && parsed >= PRESENCE_TIMEOUT_FLOOR_MS && parsed <= PRESENCE_TIMEOUT_CEILING_MS
+        ? parsed
+        : DEFAULT_PRESENCE_TIMEOUT_MS;
+}
+/** Race a promise against a timeout. Rejects with a timeout error if exceeded.
+ *  (Same idiom as session-start-hook.ts's withTimeout — duplicated rather than
+ *  imported to keep this module dependency-free of that one; it's four lines.) */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("presence_post_timeout")), ms);
+        timer.unref?.();
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+// ─── POST body ──────────────────────────────────────────────────────────────
+/**
+ * Build the POST /Presence body. Exported so tests can pin the exact shape.
+ * Never includes agentId — identity is attributed server-side from the
+ * Ed25519 signature on the request (Presence.post(), agent-auth.ts), exactly
+ * like flair_workspace_set / flair_orgevent in index.ts. currentTask is
+ * omitted (not sent as null/empty) when absent, so callers that don't know a
+ * task can still heartbeat without explicitly clearing one that was set
+ * earlier — see postPresenceSafe()'s doc comment for why that matters.
+ *
+ * Natural-presence: this body always carries `activity`, and the server stamps
+ * `activityUpdatedAt` (resources/Presence.ts, buildPresenceRecord) on any beat
+ * that asserts activity/task — so a working agent keeps activity fresh, and one
+ * that stops lets it decay to last-known automatically (no manual clear). A
+ * future liveness-only beat (this body without `activity`) would refresh
+ * lastHeartbeatAt without re-stamping activity — the server treats the two
+ * independently.
+ */
+export function buildPresenceBody(activity, currentTask) {
+    const body = { activity };
+    if (currentTask)
+        body.currentTask = currentTask;
+    return body;
+}
+/**
+ * POST /Presence and NEVER throw or reject — every failure mode (timeout,
+ * network error, 401/403/500 from the server, a malformed response) is
+ * caught and swallowed here, in this one place, so every call site gets the
+ * guarantee for free instead of re-implementing it. Not awaiting the
+ * returned promise is what makes a call site "fire and forget"; the promise
+ * itself resolving-never-rejecting is what makes doing that safe (no
+ * unhandled rejection even if a caller forgets the `.catch()` belt-and-
+ * suspenders).
+ *
+ * currentTask is intentionally the caller's responsibility, not derived here:
+ * Presence.post() (resources/Presence.ts) treats an ABSENT currentTask as an
+ * explicit clear — `sanitizeCurrentTask(undefined)` returns `null`, which then
+ * overwrites any previously-set task on every merge. That's correct for the
+ * CLI (`flair presence set --activity X` with no `--task` IS an explicit "no
+ * task" statement) but wrong for an automatic heartbeat, which should never
+ * silently erase a task a human or bootstrap() set minutes earlier. Callers
+ * that want tasks preserved across heartbeats must track and re-pass the last
+ * known task themselves (see index.ts's `lastKnownTask` / session-start-hook's
+ * per-invocation scope) — this function just forwards whatever it's given.
+ */
+export async function postPresenceSafe(poster, activity, currentTask, timeoutMs) {
+    try {
+        await withTimeout(poster.request("POST", "/Presence", buildPresenceBody(activity, currentTask)), timeoutMs);
+    }
+    catch {
+        // Silent by design — see doc comment above. A flair instance that's down
+        // or slow must never slow down or break the caller.
+    }
+}

package/dist/session-start-hook.d.ts

@@ -26,12 +26,23 @@
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
  *
+ * AUTO-PRESENCE (flair#598)
+ * -------------------------
+ * A session starting is the clearest "this agent is alive" signal flair-mcp
+ * gets, so this hook also fires a best-effort `POST /Presence` heartbeat
+ * alongside bootstrap — see ./presence.ts. It runs CONCURRENTLY with the
+ * bootstrap call (not serially after it), reuses the SAME signed request
+ * path (Ed25519, no new auth mechanism), and is bounded by its own short
+ * timeout so it can never add meaningful latency or turn a working bootstrap
+ * into a no-op. Manual `flair presence set` keeps working unchanged.
+ *
  * CONFIG (env, read identically to the MCP server)
  * ------------------------------------------------
  *   FLAIR_AGENT_ID   (required — absent → no-op)  agent identity
  *   FLAIR_URL        (default http://localhost:19926 via flair-client)
  *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
  *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
+ *   FLAIR_PRESENCE_TIMEOUT_MS (default 3000; clamped 500..10000 — see ./presence.ts)
  *
  * USAGE — register in ~/.claude/settings.json:
  *   {
@@ -43,8 +54,14 @@
  *     }
  *   }
  */
-/** Minimal surface of FlairClient this hook depends on (eases testing). */
-interface BootstrapClient {
+import { type PresencePoster } from "./presence.js";
+/** Minimal surface of FlairClient this hook depends on (eases testing).
+ *  `request` is optional and structurally matches PresencePoster (presence.ts)
+ *  — the real FlairClient always has it. When present, this hook also fires a
+ *  best-effort presence heartbeat (flair#598) alongside bootstrap; when
+ *  absent (e.g. a lightweight test stub that only implements bootstrap()),
+ *  the heartbeat is silently skipped — no behavior change for those tests. */
+interface BootstrapClient extends Partial<PresencePoster> {
     bootstrap(opts: {
         maxTokens?: number;
         channel?: string;

package/dist/session-start-hook.js

@@ -26,12 +26,23 @@
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
  *
+ * AUTO-PRESENCE (flair#598)
+ * -------------------------
+ * A session starting is the clearest "this agent is alive" signal flair-mcp
+ * gets, so this hook also fires a best-effort `POST /Presence` heartbeat
+ * alongside bootstrap — see ./presence.ts. It runs CONCURRENTLY with the
+ * bootstrap call (not serially after it), reuses the SAME signed request
+ * path (Ed25519, no new auth mechanism), and is bounded by its own short
+ * timeout so it can never add meaningful latency or turn a working bootstrap
+ * into a no-op. Manual `flair presence set` keeps working unchanged.
+ *
  * CONFIG (env, read identically to the MCP server)
  * ------------------------------------------------
  *   FLAIR_AGENT_ID   (required — absent → no-op)  agent identity
  *   FLAIR_URL        (default http://localhost:19926 via flair-client)
  *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
  *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
+ *   FLAIR_PRESENCE_TIMEOUT_MS (default 3000; clamped 500..10000 — see ./presence.ts)
  *
  * USAGE — register in ~/.claude/settings.json:
  *   {
@@ -45,6 +56,7 @@
  */
 import { FlairClient } from "@tpsdev-ai/flair-client";
 import { basename } from "node:path";
+import { deriveActivity, postPresenceSafe, resolvePresenceTimeoutMs } from "./presence.js";
 /** Claude Code SessionStart additionalContext hard limit (chars). */
 const MAX_CHARS = 10_000;
 /** Token budget for the bootstrap call — matches the proven prototype. */
@@ -120,9 +132,23 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
     }
     const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
     const project = basename(cwd) || undefined;
+    const client = makeClient(agentId);
+    // Auto-presence (flair#598): a session starting is the clearest "this
+    // agent is alive" signal available. Fired CONCURRENTLY with the bootstrap
+    // call below (not serially after it) and bounded by its own short timeout
+    // (resolvePresenceTimeoutMs(), default 3s) — postPresenceSafe() never
+    // throws (see presence.ts's fail-open contract), so this can never turn a
+    // working bootstrap into a no-op, and awaiting `presenceDone` below can
+    // never add meaningful latency beyond what bootstrap already budgets
+    // (resolveTimeoutMs(), default 8s). No currentTask here: the SessionStart
+    // payload doesn't carry a task description (unlike the MCP `bootstrap`
+    // tool call — see index.ts), so this only ever sets `activity`, leaving
+    // currentTask exactly whatever it already was.
+    const presenceDone = typeof client.request === "function"
+        ? postPresenceSafe(client, deriveActivity({ channel: "claude-code" }), undefined, resolvePresenceTimeoutMs())
+        : Promise.resolve();
     let context = "";
     try {
-        const client = makeClient(agentId);
         const res = await withTimeout(Promise.resolve(client.bootstrap({
             maxTokens: BOOTSTRAP_MAX_TOKENS,
             channel: "claude-code",
@@ -131,8 +157,10 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
         context = res && res.context ? String(res.context) : "";
     }
     catch {
+        await presenceDone;
         return NOOP_OUTPUT; // flair unreachable / auth error / timeout → no-op
     }
+    await presenceDone;
     if (!context.trim())
         return NOOP_OUTPUT;
     if (context.length > MAX_CHARS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.20.1",
+    "@tpsdev-ai/flair-client": "0.22.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",