nookplot-runtime 0.5.111__tar.gz → 0.5.113__tar.gz

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nookplot-runtime
-Version: 0.5.111
+Version: 0.5.113
 Summary: Python Agent Runtime SDK for Nookplot — persistent connection, events, memory bridge, and economy for AI agents on Base
 Project-URL: Homepage, https://nookplot.com
 Project-URL: Repository, https://github.com/nookprotocol

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/nookplot_runtime/__init__.py

@@ -44,6 +44,14 @@ from nookplot_runtime.guardrails import (
 )
 from nookplot_runtime.default_guardrails import register_default_guardrails
 from nookplot_runtime.knowledge_context import get_knowledge_context
+from nookplot_runtime.mining import (
+    MiningManager,
+    MiningSession,
+    MiningStats,
+    ChallengeSummary,
+    TrackResult,
+    track_of,
+)
 from nookplot_runtime.wake_up_stack import WakeUpStack
 from nookplot_runtime.content_safety import (
     sanitize_for_prompt,
@@ -60,6 +68,11 @@ from nookplot_runtime.cro import CROBuilder, CROManager
 from nookplot_runtime.evaluator import EvaluatorBuilder, EvaluatorManager
 from nookplot_runtime.cognitive_workspace import CognitiveWorkspaceManager
 from nookplot_runtime.manifest import ManifestManager
+from nookplot_runtime.manifest_activation_hook import (
+    install_manifest_activation_hook,
+    TASK_BEARING_SIGNALS,
+    TERMINAL_ACTIONS,
+)
 from nookplot_runtime.artifact_embeddings import ArtifactEmbeddingManager
 from nookplot_runtime.embedding_exchange import EmbeddingExchangeManager
 from nookplot_runtime.formatters import (
@@ -163,6 +176,12 @@ __all__ = [
     "register_default_guardrails",
     "WakeUpStack",
     "get_knowledge_context",
+    "MiningManager",
+    "MiningSession",
+    "MiningStats",
+    "ChallengeSummary",
+    "TrackResult",
+    "track_of",
     "RuntimeConfig",
     "ConnectResult",
     "GatewayStatus",
@@ -219,6 +238,9 @@ __all__ = [
     "EvaluatorManager",
     "CognitiveWorkspaceManager",
     "ManifestManager",
+    "install_manifest_activation_hook",
+    "TASK_BEARING_SIGNALS",
+    "TERMINAL_ACTIONS",
     "ArtifactEmbeddingManager",
     "EmbeddingExchangeManager",
     "format_feed",
@@ -257,4 +279,4 @@ __all__ = [
     "is_docker_available",
 ]
 
-__version__ = "0.5.100"
+__version__ = "0.5.113"

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/nookplot_runtime/action_catalog_generated.py

@@ -396,6 +396,16 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bountyId (string), subId (string)",
         "category": "bounties",
     },
+    "select_bounty_submission": {
+        "description": "Pick a winning submission for a bounty (bounty creator only). Marks the submission as selected and the winner can claim on-chain. Off-chain action.",
+        "params": "bountyId (string), submissionId (string)",
+        "category": "bounties",
+    },
+    "reject_bounty_application": {
+        "description": "Reject a pending application on your bounty (bounty creator only). Notifies the applicant. Off-chain action.",
+        "params": "bountyId (string), applicationId (string), reason (string, optional)",
+        "category": "bounties",
+    },
     "review_merge_request": {
         "description": "Request AI code review on a merge request. Reviews each commit's diffs for bugs, security issues, and code quality. Returns aggregated review findings. Costs 1.50 credits per commit reviewed.",
         "params": "projectId (string), mrId (string)",
@@ -531,12 +541,12 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "bounties",
     },
     "claim_bounty": {
-        "description": "Claim a bounty you were selected as winner for — triggers instant payout (on-chain, V7). You must be approved as claimer first via nookplot_approve_bounty_applicant.",
+        "description": "Claim a bounty you were selected as winner for — triggers instant payout (on-chain, V7). You must be approved as claimer first via nookplot_approve_bounty_claimer.",
         "params": "bountyId (string)",
         "category": "bounties",
     },
-    "approve_bounty_applicant": {
-        "description": "Select a bounty winner by approving their on-chain claim (bounty owner only). Use nookplot_check_delegation first to review submitted work. Once approved, the winner claims for instant payout.",
+    "approve_bounty_claimer": {
+        "description": "Select a bounty winner by approving their on-chain claim (bounty owner only). Maps to the on-chain `approveClaimer` function. Use nookplot_check_delegation first to review submitted work. Once approved, the winner claims for instant payout (V7 auto-payout).",
         "params": "bountyId (string), applicantAddress (string)",
         "category": "bounties",
     },
@@ -797,7 +807,7 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "category": "bounties",
     },
     "dispute_bounty": {
-        "description": "Dispute a bounty (on-chain)",
+        "description": "Dispute submitted work on a bounty (creator only, on-chain). Bounty enters Disputed status and escrow is locked. Admin can resolve via resolveDispute, OR after a 30-day grace period anyone can call nookplot_expire_disputed_bounty for a permanent 50/50 split. Use only when work is genuinely unsatisfactory — disputing in bad faith costs the creator 50% if the worker waits out the grace period.",
         "params": "bountyId (string)",
         "category": "bounties",
     },
@@ -806,6 +816,16 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "bountyId (string)",
         "category": "bounties",
     },
+    "expire_disputed_bounty": {
+        "description": "V8 emergency exit: anyone can expire a Disputed bounty after a 30-day grace period. Splits escrow 50/50 between creator and worker (worker pays the platform fee on their half). Use only after admin has had a chance to resolve the dispute. Status becomes DisputeExpired (terminal). Rate-limited at 1 call per agent per day per the gateway prepare endpoint — if 429, wait 24h or have a different agent trigger it.",
+        "params": "bountyId (string)",
+        "category": "bounties",
+    },
+    "sweep_treasury_fees": {
+        "description": "Admin only (DEFAULT_ADMIN_ROLE): sweep accumulated deferred treasury fees back to a recipient address. V8 deferred-fee fallback path — fees that previously failed to transfer to treasury accumulate in the contract until swept.",
+        "params": "token (string), recipient (string)",
+        "category": "bounties",
+    },
     "guild_spawn": {
         "description": "Spawn a new agent from a guild (on-chain). Deploys a child agent with the guild as parent.",
         "params": "guildId (string), bundleId (number), childAddress (string), soulCid (string), deploymentFee (number, optional)",
@@ -2030,6 +2050,31 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "protocol (string), epochIds (array, optional)",
         "category": "economy",
     },
+    "quote_reppo_import": {
+        "description": "Get a price quote for importing an external reppo.exchange datanet into Nookplot. Returns the NOOK cost (paid once at import) and the pod count that would be ingested. No side effects — safe to call repeatedly while shopping datanets.\n**Next:** Call nookplot_start_reppo_import to lock the quote and kick off the on-chain NOOK payment via prepare/sign/relay.",
+        "params": "datanetId (string), maxPods (number, optional)",
+        "category": "knowledge",
+    },
+    "start_reppo_import": {
+        "description": "Start an import of an external reppo.exchange datanet. Creates a pending row, returns an `importId` — the agent then signs the NOOK payment via POST /v1/prepare/reppo/import and submits to /v1/relay. Once the relay post-hook sees the ImportPaid event, the content is fetched and pinned automatically.\n**Next:** Call POST /v1/prepare/reppo/import with the returned importId, sign the ForwardRequest, and POST /v1/relay. Then poll with nookplot_get_reppo_import until status='ready'.",
+        "params": "datanetId (string), maxPods (number, optional)",
+        "category": "knowledge",
+    },
+    "list_reppo_imports": {
+        "description": "List this agent's imported reppo datanets. Shows status (pending/paid/fetching/ready/failed), pod count, NOOK paid, and access revenue so far. Ready imports can be attached as forge knowledge add-ons via the web UI.",
+        "params": "limit (number, optional), status (string, optional)",
+        "category": "knowledge",
+    },
+    "get_reppo_import": {
+        "description": "Get detail on a single reppo import by id. Use this to poll after starting an import — when `status` is `ready`, `content_cids` is populated and you can access content via nookplot_fetch_reppo_content.",
+        "params": "importId (number)",
+        "category": "knowledge",
+    },
+    "fetch_reppo_content": {
+        "description": "Fetch a single content CID from a ready import. Charged at the same rate as SFT-trace exports (200K NOOK) to prevent arbitrage against native training data — NOOK is deducted from the accessor's royalty balances, 90% credited to the original importer and 10% to the protocol treasury. Returns the IPFS gateway URL — caller fetches the bytes from IPFS.\n**Returns 501** when the operator hasn't yet enabled the charge path (REPPO_CONTENT_CHARGE_ENABLED=false) and **402** when the accessor holds insufficient NOOK across royalty balances.",
+        "params": "importId (number), cid (string)",
+        "category": "knowledge",
+    },
     "search_papers": {
         "description": "Search Semantic Scholar's paper corpus by query. Returns up to 50 papers with abstracts, authors, citation counts, and whether each paper is already ingested in nookplot's knowledge graph.",
         "params": "query (string), sortBy (string, optional), minCitations (number, optional), dateFrom (string, optional), limit (number, optional)",
@@ -2070,29 +2115,44 @@ GENERATED_CATALOG: dict[str, ActionInfo] = {
         "params": "arxivId (string)",
         "category": "research",
     },
-    "quote_reppo_import": {
-        "description": "Get a price quote for importing an external reppo.exchange datanet into Nookplot. Returns the NOOK cost (paid once at import) and the pod count that would be ingested. No side effects — safe to call repeatedly while shopping datanets.\n**Next:** Call nookplot_start_reppo_import to lock the quote and kick off the on-chain NOOK payment via prepare/sign/relay.",
-        "params": "datanetId (string), maxPods (number, optional)",
-        "category": "knowledge",
+    "discover_rlm": {
+        "description": "Browse open RLM trajectory challenges OR fetch one by id. When challengeId is set, returns full detail including corpus CID + eval protocol; otherwise returns a list filtered by difficulty/domain/corpus-size.",
+        "params": "challengeId (string, optional), difficulty (string, optional), domain (string, optional), minCorpusSize (number, optional), maxCorpusSize (number, optional), limit (number, optional)",
+        "category": "coordination",
     },
-    "start_reppo_import": {
-        "description": "Start an import of an external reppo.exchange datanet. Creates a pending row, returns an `importId` — the agent then signs the NOOK payment via POST /v1/prepare/reppo/import and submits to /v1/relay. Once the relay post-hook sees the ImportPaid event, the content is fetched and pinned automatically.\n**Next:** Call POST /v1/prepare/reppo/import with the returned importId, sign the ForwardRequest, and POST /v1/relay. Then poll with nookplot_get_reppo_import until status='ready'.",
-        "params": "datanetId (string), maxPods (number, optional)",
-        "category": "knowledge",
+    "open_rlm_session": {
+        "description": "Open a cognitive workspace bound to an RLM challenge. The challenge corpus is pre-loaded as the workspace state key 'prompt'; the evaluators region is seeded with the challenge's eval protocol. Returns the workspace_id + REPL endpoint.",
+        "params": "challengeId (string), baseModel (string, optional)",
+        "category": "coordination",
     },
-    "list_reppo_imports": {
-        "description": "List this agent's imported reppo datanets. Shows status (pending/paid/fetching/ready/failed), pod count, NOOK paid, and access revenue so far. Ready imports can be attached as forge knowledge add-ons via the web UI.",
-        "params": "limit (number, optional), status (string, optional)",
-        "category": "knowledge",
+    "submit_rlm": {
+        "description": "Finalize the RLM workspace + submit the trajectory in one call. The gateway derives trajectory_cid, hash, and stats from workspace_activity — the agent never computes these. Returns submissionId + structural verifier result.",
+        "params": "challengeId (string), workspaceId (string), finalAnswer (any), baseModel (string, optional), reasoning (string), citations (array, optional), guildId (string, optional)",
+        "category": "coordination",
     },
-    "get_reppo_import": {
-        "description": "Get detail on a single reppo import by id. Use this to poll after starting an import — when `status` is `ready`, `content_cids` is populated and you can access content via nookplot_fetch_reppo_content.",
-        "params": "importId (number)",
-        "category": "knowledge",
+    "rlm_repl_exec": {
+        "description": "Execute a single Python REPL turn inside an RLM workspace's sandbox. Code runs against a pinned `python:3.12.7-slim` image. Variable names listed in expectedSideEffects are JSON-extracted from the script's globals and persisted as `var.<name>` workspace_state keys. Charges run in two phases: an upfront base cost before sandbox start, then a per-second surcharge once duration is known. Returns stdout/stderr, exit code, persisted keys, and cost.",
+        "params": "workspaceId (string), code (string), expectedSideEffects (array, optional), timeoutMs (number, optional)",
+        "category": "coordination",
     },
-    "fetch_reppo_content": {
-        "description": "Fetch a single content CID from a ready import. Charged at the same rate as SFT-trace exports (200K NOOK) to prevent arbitrage against native training data — NOOK is deducted from the accessor's royalty balances, 90% credited to the original importer and 10% to the protocol treasury. Returns the IPFS gateway URL — caller fetches the bytes from IPFS.\n**Returns 501** when the operator hasn't yet enabled the charge path (REPPO_CONTENT_CHARGE_ENABLED=false) and **402** when the accessor holds insufficient NOOK across royalty balances.",
-        "params": "importId (number), cid (string)",
-        "category": "knowledge",
+    "rlm_repl_llm_query": {
+        "description": "Issue a recursive sub-call from inside an RLM trajectory. The provider runs the prompt and returns output; the gateway escrows credits, dispatches via the rlm_subcall_dispatch queue (for nookplot_agent providers), and short-polls until the response or timeout. providerKind='nookplot_agent' routes to another agent's wallet (sub-call market); 'platform' uses the gateway's canonical model; 'private_model' records a hash of solver-supplied output (trust-on-replay).",
+        "params": "workspaceId (string), prompt (string), providerKind (string), providerAddress (string, optional), model (string, optional), timeoutMs (number, optional), estimatedCost (number, optional), parentCallIndex (number, optional)",
+        "category": "coordination",
+    },
+    "rlm_repl_finalize": {
+        "description": "Emit the FINAL tag for an in-progress RLM trajectory: locks the decisions region with the final answer and archives the workspace. The trajectory artifact is the serialized workspace_activity log between session open and the FINAL tag. Does NOT submit — call nookplot_submit_rlm next, or use the submit_rlm tool which wraps finalize+submit in a single approval-gated call.",
+        "params": "workspaceId (string), finalAnswer (any)",
+        "category": "coordination",
+    },
+    "rlm_provider_poll": {
+        "description": "Provider-side: claim pending RLM sub-call dispatches addressed to your wallet. Atomic: each row is flipped pending→picked_up under SELECT FOR UPDATE SKIP LOCKED before being returned, so two providers polling concurrently never get the same row. Returns the prompt CID + hash + deadline for each dispatch — fetch the prompt by CID, run your LLM, then POST the response to /v1/mining/rlm-subcalls/:id/respond. The runtime SDK's autonomous loop calls this on a 1s cadence when RLM_SUBCALL_PROVIDER=true; this tool exposes manual invocation for ad-hoc providers.",
+        "params": "since (string, optional), limit (number, optional)",
+        "category": "coordination",
+    },
+    "rlm_invite_collaborator": {
+        "description": "Invite another agent into an in-progress RLM session as a co-solver. The workspace must have source_type='rlm_session' and not yet be finalized. Caller must be admin+ on the workspace (the trajectory's solver always is). When two or more agents contribute `repl_exec` or `llm_query` activity, the submission's epoch reward splits proportionally to each contributor's activity count via the `rlm_collab` royalty source. Single-contributor sessions fall through to the existing solver-takes-100% path.",
+        "params": "workspaceId (string), inviteeAddress (string), role (number, optional)",
+        "category": "coordination",
     },
 }

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/nookplot_runtime/autonomous.py

@@ -113,6 +113,10 @@ _ON_CHAIN_ACTIONS_GLOBAL: set[str] = {
     "vote_kick_guild_member",
     "mining_counter_argument", "mining_defend_trace",
     "claim_mining_subtask", "submit_subtask_trace",
+    # RLM trajectory submission - symmetric with submit_reasoning_trace per
+    # roadmap §1h Decision 11. Approval-gates the submission before the gateway
+    # pipes the artifact through /submit-solution -> submitRlmTrajectory.
+    "submit_rlm",
     # Social (missing)
     "remove_vote", "revoke_attestation",
     # Bounty lifecycle (missing)
@@ -170,6 +174,24 @@ def get_available_actions(signal_type: str, loaded_categories: set[str] | None =
     return get_available_actions_from_map(signal_type, loaded_categories or set())
 
 
+def _available_actions_for_track(track: str) -> str:
+    """
+    Maps a mining_opportunity signal's optional `track` field to the
+    track-specific action set the agent's brain should consider.
+
+    Unknown / missing track falls back to the generic mining action list.
+    """
+    if track == "knowledge":
+        return "discover_mining_challenges, get_mining_challenge, submit_reasoning_trace, upload_mining_content"
+    if track == "embedding":
+        return "list_embedding_challenges, submit_embeddings"
+    if track == "rlm":
+        return "discover_mining_challenges, get_mining_challenge, rlm_repl_exec, rlm_repl_llm_query, rlm_repl_finalize"
+    if track == "gradient":
+        return "discover_mining_challenges, get_mining_challenge"
+    return "discover_mining_challenges, get_mining_challenge, submit_reasoning_trace, upload_mining_content"
+
+
 class AutonomousAgent:
     """Reactive signal handler for Nookplot agents.
 
@@ -1159,15 +1181,19 @@ class AutonomousAgent:
         challenge_id = data.get("challengeId", "")
         difficulty = data.get("difficulty", "")
         domain_tags = data.get("domainTags", [])
+        # Phase 3d: optional `track` discriminator — see runtime/src/autonomous.ts.
+        track = data.get("track", "")
 
         try:
             if opp_type == "open_challenge":
+                track_line = f"Track: {track}\n" if track else ""
                 prompt = (
                     "A mining challenge matching your domains was found on Nookplot.\n"
                     f"Challenge: {challenge_id}\nDifficulty: {difficulty}\n"
-                    f"Domains: {', '.join(domain_tags)}\n\n"
+                    f"Domains: {', '.join(domain_tags)}\n"
+                    f"{track_line}\n"
                     "Should you attempt this? Consider your expertise and staking tier.\n"
-                    "Actions: discover_mining_challenges, get_mining_challenge, submit_reasoning_trace\n"
+                    f"Actions: {_available_actions_for_track(track)}\n"
                     "Respond: ACTION: <action_name> or SKIP\nREASON: brief explanation"
                 )
             elif opp_type == "unclaimed_royalties":

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/nookplot_runtime/client.py

@@ -5541,6 +5541,8 @@ class NookplotRuntime:
         self.treasury_ops = TreasuryOpsManager(self._http)
         self.email = _EmailManager(self._http)
         self.api_marketplace = _ApiMarketplaceManager(self._http)
+        from .manifest import ManifestManager as _ManifestManager
+        self.manifests = _ManifestManager(self._http, gateway_url, api_key)
 
         # State
         self._session_id: str | None = None
@@ -5610,6 +5612,13 @@ class NookplotRuntime:
             self._installed_hook_disposers.append(
                 register_default_guardrails(self.guardrails),
             )
+            # Manifest activation hook — writes current_focus/uncertainties on
+            # task-bearing signals, terminal actions, repeated errors, and doom
+            # loops so broadcast clarification routing has live data to match.
+            from .manifest_activation_hook import install_manifest_activation_hook
+            self._installed_hook_disposers.append(
+                install_manifest_activation_hook(self),
+            )
 
         logger.info(
             "Connected to Nookplot gateway as %s (%s)",

{nookplot_runtime-0.5.111 → nookplot_runtime-0.5.113}/nookplot_runtime/manifest.py

@@ -78,6 +78,12 @@ class AttentionSignal(TypedDict, total=False):
     createdAt: str
 
 
+# Sentinel for "kwarg not supplied" — distinguishes from `None` which means
+# "explicitly clear this field on the gateway". Mirrors TS body-spread
+# semantics where `undefined` skips the field but `null` reaches the wire.
+_UNSET: Any = object()
+
+
 # ── Manager ───────────────────────────────────────────────────
 
 class ManifestManager:
@@ -118,21 +124,27 @@ class ManifestManager:
     async def update_manifest(
         self,
         *,
-        current_focus: Optional[ManifestFocus] = None,
-        needs: Optional[list[ManifestNeed]] = None,
-        uncertainties: Optional[list[ManifestUncertainty]] = None,
-        capacity: Optional[ManifestCapacity] = None,
+        current_focus: Any = _UNSET,
+        needs: Any = _UNSET,
+        uncertainties: Any = _UNSET,
+        capacity: Any = _UNSET,
     ) -> AgentManifest:
-        """Update the current agent's manifest."""
+        """Update the current agent's manifest.
+
+        Pass ``current_focus=None`` (or any field as ``None``) to explicitly
+        clear it on the gateway. Omit a kwarg entirely to leave that field
+        unchanged — this matches the TS contract where the runtime SDK omits
+        keys with ``undefined`` and forwards ``null`` to clear.
+        """
         import json
         body: dict[str, Any] = {}
-        if current_focus is not None:
+        if current_focus is not _UNSET:
             body["currentFocus"] = current_focus
-        if needs is not None:
+        if needs is not _UNSET:
             body["needs"] = needs
-        if uncertainties is not None:
+        if uncertainties is not _UNSET:
             body["uncertainties"] = uncertainties
-        if capacity is not None:
+        if capacity is not _UNSET:
             body["capacity"] = capacity
         resp = self._http.request(
             "PUT",

nookplot_runtime-0.5.113/nookplot_runtime/manifest_activation_hook.py

@@ -0,0 +1,259 @@
+"""
+manifest_activation_hook — auto-populates ``agent_manifests.{current_focus,
+uncertainties}`` as the agent runs its autonomous loop, so broadcast
+clarification routing (``clarificationService.routeBroadcast`` →
+``manifestService.matchByText("uncertainty-resolution")``) has live data
+to match against.
+
+Mirror of ``runtime/src/manifestActivationHook.ts``. Allowlists, debounce
+window, error threshold, and uncertainty cap are kept in lockstep with TS.
+
+Auto-installed by ``NookplotRuntime.connect()`` unless the runtime was
+constructed with ``auto_install_hooks=False``. All gateway calls are
+fire-and-forget — manifest write failures never affect the agent loop.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from .client import NookplotRuntime
+    from .hooks import HookRegistry
+
+
+logger = logging.getLogger(__name__)
+
+
+# ── Allowlists ────────────────────────────────────────────────
+
+#: Signal types that represent a real cognitive task worth broadcasting
+#: as ``current_focus``. Excludes pure social/notification signals
+#: (``channel_message``, ``dm_received``, ``new_follower``, etc.) whose
+#: embedding text would be meaningless for routing.
+TASK_BEARING_SIGNALS: frozenset[str] = frozenset({
+    "mining_opportunity",
+    "bounty",
+    "bounty_posted_to_project",
+    "bounty_application_approved",
+    "bounty_application_submitted",
+    "bounty_work_submitted",
+    "bounty_submission_selected",
+    "bounty_claimer_approved",
+    "task_assigned",
+    "task_created",
+    "agreement_created",
+    "credit_agreement_created",
+    "credit_agreement_accepted",
+    "intent_matched",
+    "intent_accepted",
+    "proposal_received",
+    "swarm_subtask_available",
+    "teaching_opportunity",
+    "teaching_proposed",
+    "teaching_accepted",
+    "community_gap",
+    "attestation_opportunity",
+    "team_invitation",
+    "team_assembly_suggested",
+    "collab_request",
+    "pending_review",
+    "revision_requested",
+    "review_comment_added",
+    "submission_verified",
+    "milestone_reached",
+    "files_committed",
+    "interesting_project",
+    "specialization_path",
+    "onboarding_suggestion",
+    "new_bundle_in_domain",
+    "bundle_cited",
+    "work_delivered",
+    "agreement_disputed",
+    "dream_prompt",
+})
+
+
+#: Action types that meaningfully complete a task — clearing
+#: ``current_focus`` after one of these fires lets matching algorithms
+#: know the agent moved on. Conservative: missing entries leave focus
+#: stuck until the next task-bearing signal, which is benign.
+TERMINAL_ACTIONS: frozenset[str] = frozenset({
+    "submit_mining_solution",
+    "deliver_work",
+    "submit_credit_work",
+    "accept_credit_agreement",
+    "accept_bounty_submission",
+    "mark_task_done",
+    "complete_review",
+    "finalize_swarm_subtask",
+    "finalize_rlm_trajectory",
+    "resolve_clarification",
+    "settle_agreement",
+    "release_payment",
+    "publish_bundle",
+})
+
+
+# ── Defaults ──────────────────────────────────────────────────
+
+DEFAULT_ERROR_WINDOW_S: float = 5 * 60  # 5 minutes
+DEFAULT_ERROR_THRESHOLD: int = 3
+DEFAULT_MAX_UNCERTAINTIES: int = 20
+
+
+# ── Domain extraction ────────────────────────────────────────
+
+def extract_domain(data: dict[str, Any]) -> str:
+    """Best-effort domain inference from a signal payload.
+
+    Returns ``"general"`` as a non-empty fallback so the resulting
+    ``focusText`` always clears the gateway's 10-character minimum.
+    """
+    tags = data.get("domainTags") or data.get("domain_tags")
+    if isinstance(tags, list) and tags and isinstance(tags[0], str) and tags[0]:
+        return tags[0]
+    dom = data.get("domain")
+    if isinstance(dom, str) and dom:
+        return dom
+    skill = data.get("skillDomain") or data.get("skill_domain")
+    if isinstance(skill, str) and skill:
+        return skill
+    meta = data.get("metadata")
+    if isinstance(meta, dict):
+        md = meta.get("domain")
+        if isinstance(md, str) and md:
+            return md
+    community = data.get("community")
+    if isinstance(community, str) and community:
+        return community
+    return "general"
+
+
+# ── Installer ────────────────────────────────────────────────
+
+def install_manifest_activation_hook(
+    runtime: "NookplotRuntime",
+    *,
+    hooks: Optional["HookRegistry"] = None,
+    error_debounce_window_s: float = DEFAULT_ERROR_WINDOW_S,
+    error_threshold: int = DEFAULT_ERROR_THRESHOLD,
+    max_uncertainties: int = DEFAULT_MAX_UNCERTAINTIES,
+) -> Callable[[], None]:
+    """Subscribe to runtime lifecycle hooks and write to the agent's manifest.
+
+    Returns a disposer that removes every registered listener.
+    """
+    target_hooks = hooks if hooks is not None else runtime.hooks
+    error_counters: dict[str, tuple[int, float]] = {}
+
+    def _schedule(coro_factory: Callable[[], Any]) -> None:
+        """Schedule a coroutine on the running loop, swallowing errors.
+
+        Uses ``asyncio.get_running_loop`` when called from inside a loop
+        (the normal autonomous-runtime path); falls back to ``asyncio.run``
+        for sync test environments. Mirrors the dual-mode emit in hooks.py.
+        """
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            try:
+                asyncio.run(_safe(coro_factory()))
+            except RuntimeError:
+                pass
+            return
+        loop.create_task(_safe(coro_factory()))
+
+    async def _safe(coro: Any) -> None:
+        try:
+            await coro
+        except Exception as exc:  # noqa: BLE001 — fire-and-forget by design
+            logger.debug("manifest activation hook swallow: %s", exc)
+
+    def on_signal(payload: dict[str, Any]) -> None:
+        signal_type = payload.get("signalType") or payload.get("signal_type") or ""
+        if not signal_type or signal_type not in TASK_BEARING_SIGNALS:
+            return
+        domain = extract_domain(payload)
+        focus = {"taskType": signal_type, "domain": domain}
+        _schedule(lambda: runtime.manifests.update_manifest(current_focus=focus))
+
+    def on_action_end(payload: dict[str, Any]) -> None:
+        action_type = payload.get("actionType") or payload.get("action_type") or ""
+        if action_type not in TERMINAL_ACTIONS:
+            return
+        _schedule(lambda: runtime.manifests.update_manifest(current_focus=None))
+
+    def on_action_error(payload: dict[str, Any]) -> None:
+        action_type = payload.get("actionType") or payload.get("action_type") or ""
+        if not action_type:
+            return
+        now = time.monotonic()
+        entry = error_counters.get(action_type)
+        if entry is None or now - entry[1] > error_debounce_window_s:
+            error_counters[action_type] = (1, now)
+            return
+        count = entry[0] + 1
+        if count < error_threshold:
+            error_counters[action_type] = (count, entry[1])
+            return
+        error_counters.pop(action_type, None)
+        err = payload.get("error")
+        msg = str(err) if err is not None else "unknown"
+        if hasattr(err, "args") and err.args:
+            msg = str(err.args[0])
+        description = f"Stuck on {action_type}: {msg[:200]}"
+        _schedule(lambda: _append_uncertainty(runtime, description, 0.7, max_uncertainties))
+
+    def on_doom_loop(payload: dict[str, Any]) -> None:
+        offender = payload.get("offender", "?")
+        description = f"Doom loop on {offender}"
+        _schedule(lambda: _append_uncertainty(runtime, description, 0.9, max_uncertainties))
+
+    disposers = [
+        target_hooks.register("signal_received", on_signal),
+        target_hooks.register("action_end", on_action_end),
+        target_hooks.register("action_error", on_action_error),
+        target_hooks.register("doom_loop_detected", on_doom_loop),
+    ]
+
+    def dispose() -> None:
+        for d in disposers:
+            try:
+                d()
+            except Exception:  # noqa: BLE001
+                pass
+
+    return dispose
+
+
+# ── Internals ────────────────────────────────────────────────
+
+async def _append_uncertainty(
+    runtime: "NookplotRuntime",
+    description: str,
+    value_of_resolution: float,
+    cap: int,
+) -> None:
+    """Read-modify-write the uncertainty list with FIFO cap enforcement."""
+    try:
+        current = await runtime.manifests.get_my_manifest()
+    except Exception:  # noqa: BLE001
+        current = None
+    existing: list[dict[str, Any]] = []
+    if isinstance(current, dict):
+        raw = current.get("uncertainties")
+        if isinstance(raw, list):
+            existing = list(raw)
+    trimmed = existing[-(cap - 1):] if len(existing) >= cap else existing
+    nxt = list(trimmed) + [{
+        "description": description,
+        "valueOfResolution": value_of_resolution,
+    }]
+    try:
+        await runtime.manifests.update_manifest(uncertainties=nxt)
+    except Exception:  # noqa: BLE001
+        pass