Hindsight managed runtime modes

docs/design/built-in-first-party-packs.md

@@ -80,9 +80,9 @@ shipped first-party packs directory, and resolve those packs *in place* as a
 dedicated band in `buildPackList()`.** They are NOT copied into any scope's
 `.bobbit/config/market-packs/`.
 
-"Auto-installed" therefore means **present + active by default**: a built-in pack
-is always resolvable; the only opt-out is **disable** via the #734 activation
-overrides (default = enabled). Updates ride the app upgrade for free (the shipped
+"Auto-installed" therefore means **present in the built-in band**: most built-in packs are
+active by default, while a pack that declares `defaultDisabled: true` resolves with all of its
+contributions disabled until explicitly enabled or already configured. Updates ride the app upgrade for free (the shipped
 dir is replaced on install/upgrade).
 
 ### Rejected alternative — copy-install + opt-out ledger

docs/design/hindsight-pack-external.md

@@ -3,8 +3,10 @@
 Status: design / implementation blueprint. Scope is the **external-URL** Hindsight memory pack:
 a REST client, an in-process stub harness, the lifecycle provider, pack routes + config surface,
 bank/tag derivation, dormancy, and built-in-band registration (dormant). Managed Docker runtime,
-Postgres, volumes, deployment-mode selection, the explicit agent tools, and the native panel are
-**out of scope** (G2.3 / G3 / G4).
+Postgres, volumes, deployment-mode selection, the explicit agent tools, and the native panel were
+**out of scope** of this blueprint (G2.3 / G3 / G4) and shipped later: the managed runtime in P3,
+the native panel in P4, and the agent tools `hindsight_recall/retain/reflect` in **P5** (see
+[hindsight-memory.md → Agent tools](../hindsight-memory.md#agent-tools)).
 
 > Authority notes. This folds the impl-plan's **G2.1 + G2.2** ([extension-platform-implementation-plan.md
 > §G2](extension-platform-implementation-plan.md)) and applies two owner overrides recorded for
@@ -73,7 +75,7 @@ Pack layout (this goal):
 ```
 market-packs/hindsight/
   pack.yaml                  # schema 2; contents.providers: [memory]; routes
-  providers/memory.yaml      # kind: memory; hooks: all five; config surface
+  providers/memory.yaml      # kind: memory; lifecycle hooks; config surface
   src/hindsight-client.ts    # → lib/hindsight-client.mjs
   src/provider.ts            # → lib/provider.mjs
   src/routes.ts              # → lib/routes.mjs
@@ -89,7 +91,7 @@ schema: 2
 name: hindsight
 description: >-
   Persistent agent memory backed by Hindsight (recall/retain/reflect over a shared,
-  tag-scoped bank). Dormant until a Hindsight URL is configured. See docs/design/agent-memory.md.
+  tag-scoped bank). Default-disabled until Marketplace setup enables/configures it. See docs/design/agent-memory.md.
 version: 1.0.0
 contents:
   roles: []
@@ -114,9 +116,9 @@ routes:
 id: memory
 kind: memory
 module: ../lib/provider.mjs
-hooks: [sessionSetup, beforePrompt, afterTurn, beforeCompact, sessionShutdown]
-budget: { maxTokens: 1200, timeoutMs: 1500 }
-defaultEnabled: true        # activation is additionally gated on externalUrl (see below)
+hooks: [sessionSetup, beforePrompt, afterTurn, beforeCompact, sessionShutdown, goalCompleted]
+budget: { maxTokens: 1200, timeoutMs: 4500 }
+defaultEnabled: true        # provider default once the pack itself is enabled/configured
 config:
   mode:        { type: enum, values: [external, managed], default: external }  # managed reserved for G3
   externalUrl: { type: string, optional: true }
@@ -127,7 +129,7 @@ config:
   autoRecall:  { type: boolean, default: true }
   autoRetain:  { type: boolean, default: true }
   recallBudget:{ type: number, default: 1200 }
-  timeoutMs:   { type: number, default: 1500 }
+  timeoutMs:   { type: number, default: 4000 }
 activation:
   requiresConfig: [externalUrl]  # host omits the provider entirely until configured
 ```
@@ -136,9 +138,11 @@ Loaded via the **pack-contributions path** (`pack-contributions.ts`-style loader
 `PackContributionRegistry`, keyed `(packId, contributionId)`), per impl-plan §0.2 — NOT a new
 `EntityType`. The provider runs on the Extension Host worker tier exactly like the `provider-demo`
 fixture. Per-entity activation still respects `DisabledRefs.providers` / `pack_activation`, but
-Hindsight also declares `activation.requiresConfig: [externalUrl]`. The registry/loader omits this
-provider until the effective config has a non-empty `externalUrl`; this is what prevents bridge
-injection and per-turn hook calls on a fresh install.
+Hindsight also declares pack-level `defaultDisabled: true` and provider-level activation gates. On
+fresh installs the pack-level overlay disables all contributions; after setup enables/configures the
+pack, `activation.requiresConfig: [externalUrl]` (or managed-mode `activeWhenConfig` in the current
+pack) keeps the provider omitted until the effective config/runtime is usable. This is what prevents
+bridge injection and per-turn hook calls before opt-in.
 
 ---
 
@@ -172,7 +176,7 @@ export function createClient(cfg: {
   baseUrl: string;
   apiKey?: string;
   namespace?: string;   // default "default"
-  timeoutMs?: number;   // default 1500
+  timeoutMs?: number;   // default 4000
 }): HindsightClient;
 ```
 
@@ -186,7 +190,7 @@ export class HindsightError extends Error {
 ```
 
 - Every method wraps its `fetch` in an `AbortController` armed with `cfg.timeoutMs` (default
-  **1500 ms**). Abort ⇒ `HindsightError{ kind:"timeout" }`, thrown **within budget** (the test
+  **4000 ms**). Abort ⇒ `HindsightError{ kind:"timeout" }`, thrown **within budget** (the test
   asserts elapsed ≤ a small margin over `timeoutMs`).
 - Non-2xx ⇒ `HindsightError{ kind:"http", status }`.
 - DNS/connection refused/socket error ⇒ `HindsightError{ kind:"network" }`.
@@ -289,13 +293,14 @@ queue, last error, optional bank-ensured marker) lives in `ctx.host.store`, neve
 
 ### 5.1 Dormancy gate (the central invariant)
 
-Before any hook does work it evaluates **`isActive(ctx)`**: `config.mode === "external"` AND
-`config.externalUrl` is a non-empty string. If not active, **every hook returns immediately**:
-`sessionSetup`/`beforePrompt` ⇒ `{ blocks: [] }`; `afterTurn`/`beforeCompact`/`sessionShutdown`
-⇒ no-op. This is a defensive backstop. The primary dormant guarantee is earlier in the host:
-`activation.requiresConfig: [externalUrl]` means an unconfigured pack contributes no active
-provider, so the provider bridge is not injected and no per-turn hook route is called. No client is
-constructed, no Hindsight network is touched, and spawn args/prompt text stay at the no-pack
+Before any hook does work it evaluates **`isActive(ctx)`**: external mode requires a non-empty
+`externalUrl`, while managed modes require a host-injected running runtime. If not active, **every
+hook returns immediately**: `sessionSetup`/`beforePrompt` ⇒ `{ blocks: [] }`;
+`afterTurn`/`beforeCompact`/`sessionShutdown`/`goalCompleted` ⇒ no-op. This is a defensive
+backstop. The primary dormant guarantee is earlier in the host: `defaultDisabled: true` disables all
+pack contributions on a fresh unconfigured install, and provider activation gates keep the provider
+omitted until setup/config makes it usable. No client is constructed, no Hindsight network is
+touched, and spawn args/prompt text stay at the no-pack
 baseline until configured (§9.5).
 
 Health is treated as a runtime condition layered on top of activation: when active but the client
@@ -415,13 +420,14 @@ The provider must receive a **flat** config object that is **store-over-yaml-def
 
 1. The loader first resolves each `providers/memory.yaml` config schema entry to its `.default`
    value (or `undefined` for optional fields), producing values such as `mode: "external"`,
-   `bank: "bobbit"`, `namespace: "default"`, `autoRecall: true`, and `timeoutMs: 1500` — not raw
+   `bank: "bobbit"`, `namespace: "default"`, `autoRecall: true`, and `timeoutMs: 4000` — not raw
    `{ type, default }` schema objects.
 2. The `config` route persists validated overrides to the pack store.
 3. The loader overlays persisted store config over the flat defaults before constructing
    `ctx.config`.
-4. The provider activation filter evaluates `activation.requiresConfig` against this same
-   effective flat config; absent `externalUrl` means the provider is omitted before bridge injection.
+4. The default-disabled pack overlay disables all contributions on fresh unconfigured installs;
+   after setup enables/configures the pack, provider activation filters evaluate the effective flat
+   config/runtime before bridge injection.
 
 If G1.1 currently exposes only static yaml, both the default-resolution step and the store-config
 overlay are added **in the loader path, not the provider** (so every provider benefits and
@@ -495,6 +501,11 @@ A separate defensive unit test calls the provider hooks directly with no `extern
 
 ## 11. Non-goals (tracked elsewhere)
 
-- Explicit agent tools `hindsight_recall/retain/reflect` + native panel + entrypoints — **G2.3**.
-- Managed Docker runtime + Postgres + `~/.hindsight` + deployment-mode selection — **G3**.
+- Explicit agent tools `hindsight_recall/retain/reflect` — **G2.3** (shipped in **P5**; see
+  [hindsight-memory.md → Agent tools](../hindsight-memory.md#agent-tools)). The **native panel +
+  entrypoints** half of G2.3 shipped in **P4** — see
+  [hindsight-memory.md → Native config & status panel](../hindsight-memory.md#native-config--status-panel)
+  and [hindsight-panel-p4-implementation.md](hindsight-panel-p4-implementation.md).
+- Managed Docker runtime + Postgres + `~/.hindsight` + deployment-mode selection — **G3** (shipped
+  in **P3**; see [managed-runtimes.md](../managed-runtimes.md#p3--deployment-modes-consent--lifecycle)).
 - Mental-models / reflect UI / cross-engine dedupe / cost surfacing — **G4**.