forge-openclaw-plugin 0.3.10 → 0.3.11

package/dist/companion-iroh-src/src/lib.rs

@@ -1,6 +1,9 @@
+use std::collections::HashMap;
 use std::ffi::{CStr, CString, c_char};
-use std::time::Duration;
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::{Duration, Instant};
 
+use iroh::endpoint::Connection;
 use iroh::{Endpoint, SecretKey};
 use protocol::{
     BridgeRequest, BridgeResponse, COMPANION_ALPN, FORGE_AGENT_NAME, ForgeHttpRequest,
@@ -12,6 +15,129 @@ use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
 pub mod protocol;
 
 const MAX_FRAME_BYTES: usize = 50 * 1024 * 1024;
+const IROH_CLIENT_TIMING_HEADER: &str = "x-forge-iroh-client-timing-ms";
+const IROH_CLIENT_CONNECTION_REUSED_HEADER: &str = "x-forge-iroh-client-connection-reused";
+const FFI_RUNTIME_WORKER_THREADS: usize = 6;
+#[cfg(test)]
+const FOREGROUND_HEALTH_SYNC_STREAMS: usize = 6;
+
+struct FfiIrohState {
+    runtime: tokio::runtime::Runtime,
+    endpoint: Mutex<Option<Arc<Endpoint>>>,
+    connections: Mutex<HashMap<ConnectionCacheKey, Arc<Connection>>>,
+    secret_key: SecretKey,
+}
+
+static FFI_STATE: OnceLock<Result<FfiIrohState, String>> = OnceLock::new();
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct ConnectionCacheKey {
+    node_id: String,
+    relay: Option<String>,
+    token: String,
+}
+
+impl ConnectionCacheKey {
+    fn from_payload(payload: &PairPayload) -> Self {
+        Self {
+            node_id: payload.node_id.clone(),
+            relay: payload.relay.clone(),
+            token: payload.token.clone(),
+        }
+    }
+}
+
+fn ffi_state() -> Result<&'static FfiIrohState, String> {
+    match FFI_STATE.get_or_init(FfiIrohState::new) {
+        Ok(state) => Ok(state),
+        Err(error) => Err(error.clone()),
+    }
+}
+
+impl FfiIrohState {
+    fn new() -> Result<Self, String> {
+        let runtime = tokio::runtime::Builder::new_multi_thread()
+            .worker_threads(FFI_RUNTIME_WORKER_THREADS)
+            .enable_all()
+            .build()
+            .map_err(|error| format!("building Forge Iroh runtime: {error}"))?;
+        Ok(Self {
+            runtime,
+            endpoint: Mutex::new(None),
+            connections: Mutex::new(HashMap::new()),
+            secret_key: SecretKey::generate(),
+        })
+    }
+
+    async fn cached_endpoint(&self) -> Result<Arc<Endpoint>, String> {
+        if let Some(endpoint) = self.endpoint.lock().map_err(lock_error)?.as_ref().cloned() {
+            return Ok(endpoint);
+        }
+
+        let endpoint = Arc::new(
+            Endpoint::builder(iroh::endpoint::presets::N0)
+                .secret_key(self.secret_key.clone())
+                .bind()
+                .await
+                .map_err(|error| format!("binding Iroh endpoint: {error}"))?,
+        );
+        let mut guard = self.endpoint.lock().map_err(lock_error)?;
+        if let Some(existing) = guard.as_ref().cloned() {
+            return Ok(existing);
+        }
+        *guard = Some(endpoint.clone());
+        Ok(endpoint)
+    }
+
+    async fn cached_connection(
+        &self,
+        payload: &PairPayload,
+    ) -> Result<(ConnectionCacheKey, Arc<Connection>, bool), String> {
+        let key = ConnectionCacheKey::from_payload(payload);
+        if let Some(connection) = self
+            .connections
+            .lock()
+            .map_err(lock_error)?
+            .get(&key)
+            .cloned()
+        {
+            return Ok((key, connection, true));
+        }
+
+        let endpoint = self.cached_endpoint().await?;
+        let connection = Arc::new(connect_iroh(endpoint, payload).await?);
+        let mut guard = self.connections.lock().map_err(lock_error)?;
+        if let Some(existing) = guard.get(&key).cloned() {
+            return Ok((key, existing, true));
+        }
+        guard.insert(key.clone(), connection.clone());
+        Ok((key, connection, false))
+    }
+
+    fn evict_connection(&self, key: &ConnectionCacheKey, connection: &Arc<Connection>) {
+        let Ok(mut guard) = self.connections.lock() else {
+            connection.close(
+                iroh::endpoint::VarInt::from_u32(1),
+                b"forge connection cache lock failed",
+            );
+            return;
+        };
+        if guard
+            .get(key)
+            .is_some_and(|existing| Arc::ptr_eq(existing, connection))
+        {
+            guard.remove(key);
+            connection.close(
+                iroh::endpoint::VarInt::from_u32(1),
+                b"forge request stream failed",
+            );
+        }
+    }
+}
+
+fn lock_error<T>(error: std::sync::PoisonError<T>) -> String {
+    format!("Forge Iroh client state lock poisoned: {error}")
+}
 
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -87,12 +213,9 @@ fn into_c_string(value: String) -> *mut c_char {
 }
 
 fn run_ffi_http_request(request: FfiHttpRequest) -> Result<FfiHttpResponse, String> {
-    let runtime = tokio::runtime::Builder::new_current_thread()
-        .enable_all()
-        .build()
-        .map_err(|error| format!("building Forge Iroh runtime: {error}"))?;
-    runtime.block_on(async move {
-        let response = send_http_request_over_iroh(request).await?;
+    let state = ffi_state()?;
+    state.runtime.block_on(async move {
+        let response = send_http_request_over_iroh(state, request).await?;
         Ok(FfiHttpResponse {
             ok: true,
             status: Some(response.status),
@@ -103,74 +226,141 @@ fn run_ffi_http_request(request: FfiHttpRequest) -> Result<FfiHttpResponse, Stri
     })
 }
 
-async fn send_http_request_over_iroh(request: FfiHttpRequest) -> Result<ForgeHttpResponse, String> {
+async fn send_http_request_over_iroh(
+    state: &FfiIrohState,
+    request: FfiHttpRequest,
+) -> Result<ForgeHttpResponse, String> {
     validate_pair_payload(&request.pair_payload)?;
     validate_proxy_path(&request.path)?;
 
-    let endpoint = Endpoint::builder(iroh::endpoint::presets::N0)
-        .secret_key(SecretKey::generate())
-        .bind()
-        .await
-        .map_err(|error| format!("binding Iroh endpoint: {error}"))?;
-    let result = async {
-        let node_id = request
-            .pair_payload
-            .node_id
-            .parse()
-            .map_err(|error| format!("parsing Iroh node id: {error}"))?;
-        let mut addr = iroh::EndpointAddr::new(node_id);
-        if let Some(relay) = request.pair_payload.relay.as_deref() {
-            addr = addr.with_relay_url(
-                relay
-                    .parse()
-                    .map_err(|error| format!("parsing Iroh relay URL: {error}"))?,
-            );
+    let total_started_at = Instant::now();
+    let connection_started_at = Instant::now();
+    let (cache_key, conn, connection_reused) =
+        state.cached_connection(&request.pair_payload).await?;
+    let connection_ms = elapsed_ms(connection_started_at);
+    match send_request_over_connection(&conn, request).await {
+        Ok((mut response, mut timing)) => {
+            timing.connection_ms = connection_ms;
+            timing.connection_reused = connection_reused;
+            timing.total_ms = elapsed_ms(total_started_at);
+            response.headers.push(HeaderPair {
+                name: IROH_CLIENT_TIMING_HEADER.to_string(),
+                value: timing.to_header_value(),
+            });
+            response.headers.push(HeaderPair {
+                name: IROH_CLIENT_CONNECTION_REUSED_HEADER.to_string(),
+                value: if connection_reused { "1" } else { "0" }.to_string(),
+            });
+            Ok(response)
         }
-        let conn = endpoint
-            .connect(addr, COMPANION_ALPN)
-            .await
-            .map_err(|error| format!("connecting over Forge Iroh bridge: {error}"))?;
-        let (mut send, mut recv) = conn
-            .open_bi()
-            .await
-            .map_err(|error| format!("opening Iroh stream: {error}"))?;
-        write_json_frame(
-            &mut send,
-            &BridgeRequest::Connect {
-                v: PROTOCOL_VERSION,
-                token: request.pair_payload.token.clone(),
-                agent: FORGE_AGENT_NAME.to_string(),
-            },
-        )
-        .await?;
-        let ack: BridgeResponse = read_json_frame(&mut recv).await?;
-        validate_bridge_response(&ack)?;
-        write_json_frame(
-            &mut send,
-            &ForgeHttpRequest {
-                v: PROTOCOL_VERSION,
-                method: request.method,
-                path: request.path,
-                headers: request.headers,
-                body_base64: request.body_base64,
-            },
-        )
-        .await?;
-        let response = tokio::time::timeout(
-            Duration::from_secs(60),
-            read_json_frame::<ForgeHttpResponse, _>(&mut recv),
-        )
-        .await
-        .map_err(|_| "timed out waiting for Forge Iroh response".to_string())??;
-        conn.close(
-            iroh::endpoint::VarInt::from_u32(0),
-            b"forge request complete",
+        Err(error) => {
+            state.evict_connection(&cache_key, &conn);
+            Err(error)
+        }
+    }
+}
+
+async fn connect_iroh(
+    endpoint: Arc<Endpoint>,
+    payload: &PairPayload,
+) -> Result<Connection, String> {
+    let node_id = payload
+        .node_id
+        .parse()
+        .map_err(|error| format!("parsing Iroh node id: {error}"))?;
+    let mut addr = iroh::EndpointAddr::new(node_id);
+    if let Some(relay) = payload.relay.as_deref() {
+        addr = addr.with_relay_url(
+            relay
+                .parse()
+                .map_err(|error| format!("parsing Iroh relay URL: {error}"))?,
         );
-        Ok(response)
     }
-    .await;
-    endpoint.close().await;
-    result
+    endpoint
+        .connect(addr, COMPANION_ALPN)
+        .await
+        .map_err(|error| format!("connecting over Forge Iroh bridge: {error}"))
+}
+
+async fn send_request_over_connection(
+    conn: &Connection,
+    request: FfiHttpRequest,
+) -> Result<(ForgeHttpResponse, IrohClientTiming), String> {
+    let mut timing = IrohClientTiming::default();
+    let open_started_at = Instant::now();
+    let (mut send, mut recv) = conn
+        .open_bi()
+        .await
+        .map_err(|error| format!("opening Iroh stream: {error}"))?;
+    timing.open_stream_ms = elapsed_ms(open_started_at);
+
+    let bridge_started_at = Instant::now();
+    write_json_frame(
+        &mut send,
+        &BridgeRequest::Connect {
+            v: PROTOCOL_VERSION,
+            token: request.pair_payload.token.clone(),
+            agent: FORGE_AGENT_NAME.to_string(),
+        },
+    )
+    .await?;
+    let ack: BridgeResponse = read_json_frame(&mut recv).await?;
+    validate_bridge_response(&ack)?;
+    timing.bridge_ack_ms = elapsed_ms(bridge_started_at);
+
+    let write_started_at = Instant::now();
+    write_json_frame(
+        &mut send,
+        &ForgeHttpRequest {
+            v: PROTOCOL_VERSION,
+            method: request.method,
+            path: request.path,
+            headers: request.headers,
+            body_base64: request.body_base64,
+        },
+    )
+    .await?;
+    timing.write_request_ms = elapsed_ms(write_started_at);
+
+    let response_started_at = Instant::now();
+    let response = tokio::time::timeout(
+        Duration::from_secs(60),
+        read_json_frame::<ForgeHttpResponse, _>(&mut recv),
+    )
+    .await
+    .map_err(|_| "timed out waiting for Forge Iroh response".to_string())??;
+    timing.response_wait_ms = elapsed_ms(response_started_at);
+    Ok((response, timing))
+}
+
+#[derive(Debug, Default)]
+struct IrohClientTiming {
+    connection_reused: bool,
+    connection_ms: u128,
+    open_stream_ms: u128,
+    bridge_ack_ms: u128,
+    write_request_ms: u128,
+    response_wait_ms: u128,
+    total_ms: u128,
+}
+
+impl IrohClientTiming {
+    fn to_header_value(&self) -> String {
+        format!(
+            "reused={},total={},connection={},openStream={},bridgeAck={},writeRequest={},responseWait={}",
+            if self.connection_reused { 1 } else { 0 },
+            self.total_ms,
+            self.connection_ms,
+            self.open_stream_ms,
+            self.bridge_ack_ms,
+            self.write_request_ms,
+            self.response_wait_ms
+        )
+    }
+}
+
+fn elapsed_ms(started_at: Instant) -> u128 {
+    started_at.elapsed().as_millis()
 }
 
 fn validate_pair_payload(payload: &PairPayload) -> Result<(), String> {
@@ -276,4 +466,73 @@ mod tests {
     fn proxy_path_rejects_absolute_urls() {
         assert!(validate_proxy_path("https://example.com/api/v1/health").is_err());
     }
+
+    #[test]
+    fn ffi_reuses_runtime_and_endpoint_between_requests() {
+        let state = ffi_state().expect("ffi state");
+        let first = state
+            .runtime
+            .block_on(state.cached_endpoint())
+            .expect("first endpoint");
+        let second = state
+            .runtime
+            .block_on(state.cached_endpoint())
+            .expect("second endpoint");
+
+        assert!(Arc::ptr_eq(&first, &second));
+    }
+
+    #[test]
+    fn connection_cache_key_tracks_remote_and_token() {
+        let payload = PairPayload {
+            v: PROTOCOL_VERSION,
+            node_id: "node-a".to_string(),
+            token: "token-a".to_string(),
+            host_name: Some("host".to_string()),
+            relay: Some("https://relay.example".to_string()),
+        };
+        let same = PairPayload {
+            host_name: None,
+            ..payload.clone()
+        };
+        let different_token = PairPayload {
+            token: "token-b".to_string(),
+            ..payload.clone()
+        };
+
+        assert_eq!(
+            ConnectionCacheKey::from_payload(&payload),
+            ConnectionCacheKey::from_payload(&same)
+        );
+        assert_ne!(
+            ConnectionCacheKey::from_payload(&payload),
+            ConnectionCacheKey::from_payload(&different_token)
+        );
+    }
+
+    #[test]
+    fn iroh_client_timing_header_names_response_wait() {
+        let timing = IrohClientTiming {
+            connection_reused: true,
+            connection_ms: 1,
+            open_stream_ms: 2,
+            bridge_ack_ms: 3,
+            write_request_ms: 4,
+            response_wait_ms: 5,
+            total_ms: 15,
+        };
+
+        assert_eq!(
+            timing.to_header_value(),
+            "reused=1,total=15,connection=1,openStream=2,bridgeAck=3,writeRequest=4,responseWait=5"
+        );
+    }
+
+    #[test]
+    fn ffi_runtime_keeps_up_with_foreground_health_sync_window() {
+        assert!(
+            FFI_RUNTIME_WORKER_THREADS >= FOREGROUND_HEALTH_SYNC_STREAMS,
+            "Iroh FFI runtime workers should not be narrower than foreground HealthKit streams"
+        );
+    }
 }

package/dist/companion-iroh-src/src/main.rs

@@ -1,5 +1,5 @@
 use std::path::{Path, PathBuf};
-use std::time::Duration;
+use std::time::{Duration, Instant};
 
 use anyhow::{Context, anyhow};
 use base64::Engine;
@@ -16,6 +16,7 @@ use tracing::{info, warn};
 use tracing_subscriber::EnvFilter;
 
 const MAX_FRAME_BYTES: usize = 50 * 1024 * 1024;
+const IROH_HOST_TIMING_HEADER: &str = "x-forge-iroh-host-timing-ms";
 
 #[derive(Parser, Debug)]
 #[command(version, about = "Forge Companion transport over Iroh QUIC")]
@@ -276,9 +277,12 @@ async fn proxy_http_request(
             .context("decoding request body")?;
         builder = builder.body(bytes);
     }
+    let request_started_at = Instant::now();
     let response = builder.send().await.context("forwarding HTTP request")?;
+    let upstream_response_ms = request_started_at.elapsed().as_millis();
     let status = response.status().as_u16();
-    let headers = response
+    let body_started_at = Instant::now();
+    let mut headers: Vec<HeaderPair> = response
         .headers()
         .iter()
         .filter_map(|(name, value)| {
@@ -292,6 +296,15 @@ async fn proxy_http_request(
         .bytes()
         .await
         .context("reading HTTP response body")?;
+    let body_read_ms = body_started_at.elapsed().as_millis();
+    let total_ms = request_started_at.elapsed().as_millis();
+    headers.push(HeaderPair {
+        name: IROH_HOST_TIMING_HEADER.to_string(),
+        value: format!(
+            "total={},upstreamResponse={},bodyRead={}",
+            total_ms, upstream_response_ms, body_read_ms
+        ),
+    });
     Ok(ForgeHttpResponse {
         v: PROTOCOL_VERSION,
         status,

package/dist/server/server/src/app.js

@@ -5461,12 +5461,12 @@ function buildAgentOnboardingPayload(request) {
             reviewShortcutRule: "When the user is reviewing or correcting an existing record, ask what practical question they want the read or correction to answer, then narrow the saved object, timeframe, or route family first. Use the correct read posture before asking write-shaped questions: shared batch search or read hints for normal entities, wiki/calendar dedicated reads for specialized CRUD, read-model routes for overviews, and Movement, Life Force, or Workbench dedicated reads for those domain surfaces. After the read, answer the practical question before asking for any save, correction, link, run, enrichment, or publish detail. Do not reopen the whole intake unless the user is actually redefining the record.",
             readModelWriteRule: "Self-observation is note-backed and should be written through observed notes with frontmatter.observedAt only when a lightweight episode observation is the right container. Do not use it as the default bucket for Psyche material: prefer trigger_report for one emotionally meaningful episode, behavior_pattern for functional analysis of a recurring loop, behavior for one repeated move, belief_entry for a core sentence, mode_guide_session or mode_profile for a central part-state, and wiki_page for durable memory such as books, articles, concepts, sources, or personal manuals. Sleep and workout sessions stay on batch CRUD by default; use the reflective review helpers only when enriching one already-known record after review.",
             psycheOpeningQuestionRule: "Prefer a concrete opening question tied to the entity: ask when the value mattered, what happened the last time the pattern appeared, what cue or body signal came first before the behavior, what the belief starts saying about self or outcome, what feels most at risk inside the mode, what the part is trying to get the user to do or stop doing, or where the shift began in the incident. Reflect briefly before the question, choose one follow-up lane at a time, say what is becoming clearer before the next deeper question, and if several Psyche entities are visible hold the adjacent ones lightly until the main container is clear.",
-            psycheHypothesisRule: "When one concrete Psyche example is visible, a helpful hypothesis should start from evidence in the user's own example, offer one testable interpretation, name the function without blame such as protection, prediction, relief, or cost, and ask whether the danger, need, or wording fits. Use the hypothesis timing checkpoint before asking a second or third deepening question: offer a hypothesis when one concrete episode, body cue, belief sentence, behavior, or mode voice is visible and the hypothesis would change the record shape, wording, links, or next action. Do not keep asking broad exploratory Psyche questions after the cue, meaning, protection, payoff, or cost is already visible. For behavior_pattern, belief_entry, mode_profile, mode_guide_session, and trigger_report, the next helpful move is usually one active formulation plus one correction question, not another passive reflection. Do not hypothesize yet when no concrete moment is visible, the user only wants a direct mechanical save, the user is flooded or unsafe, or the only available interpretation would be diagnosis-like, an origin story, or a certainty claim. Do not present schema, mode, belief, or pattern language as a verdict. If the user corrects the hypothesis, revise it once and move toward the saveable record shape instead of asking for another broad story.",
+            psycheHypothesisRule: "When one concrete Psyche example is visible, a helpful hypothesis should start from evidence in the user's own example, offer one testable interpretation, name the function without blame such as protection, prediction, relief, or cost, and ask whether the danger, need, or wording fits. Use the hypothesis timing checkpoint before asking a second or third deepening question: offer a hypothesis when one concrete episode, body cue, belief sentence, behavior, or mode voice is visible and the hypothesis would change the record shape, wording, links, or next action. Do not keep asking broad exploratory Psyche questions after the cue, meaning, protection, payoff, or cost is already visible. For behavior_pattern, belief_entry, mode_profile, mode_guide_session, and trigger_report, the next helpful move is usually one active formulation plus one correction question, not another passive reflection. Hypotheses should reduce the formulation burden. Do not make the user prove the experience: after one hypothesis, ask one fit-or-correction question rather than a stack of evidence, origin, and repair questions. If accuracy needs grounding, ask for the smallest lived cue or contrast that would change the wording, danger, protection, payoff, cost, or record shape. Do not hypothesize yet when no concrete moment is visible, the user only wants a direct mechanical save, the user is flooded or unsafe, or the only available interpretation would be diagnosis-like, an origin story, or a certainty claim. Do not present schema, mode, belief, or pattern language as a verdict. If the user corrects the hypothesis, revise it once and move toward the saveable record shape instead of asking for another broad story.",
             mixedIntentSequencingRule: "When one user message combines several Forge jobs, identify the primary job and the order of operations before asking a follow-up. If a read changes the truth of a later write, read first: Movement timeline or box detail before correction, Workbench run or node detail before editing or publishing, and Life Force overview before changing durable assumptions when the current energy picture is uncertain. If the user asks to understand and save Psyche material plus create a support record, formulate the primary Psyche record first, then derive the flashcard, note, link, task, or habit from the accepted wording. If the user already gave the concrete action, do not ask a broad lane question; say the product sequence briefly and ask only for the missing span, wording, flow, run, node, weekday, or link that changes the next action.",
             duplicateDisambiguationRule: "Before creating or updating a normal stored entity when duplicate risk is plausible, search the shared batch entity route by entity type, distinctive title or wording, owner scope, and linked content. If a likely existing record appears, ask whether the user wants to update that record, link to it, or save a separate new record; do not reopen the whole create flow. For Psyche records, a similar belief, pattern, mode, trigger report, value, or flashcard is a formulation choice, not a duplicate error: compare the sentence, cue/payoff/cost, protective job, episode, urge sentence, or message and let the user choose update, link, or new version. For wiki_page and calendar_connection, use dedicated search/list/read routes before creating another page or connection. For Movement, Life Force, and Workbench, use the dedicated read lanes instead of batch duplicate search.",
             destructiveActionRule: "Before deleting, archiving, invalidating, overwriting, disconnecting, or substantially replacing a Forge record or specialized object, confirm the exact target and what should remain understandable. Prefer normal soft-delete for stored entities unless the user explicitly asks for permanent removal. For Psyche records, preserve therapeutic history by asking whether the old belief, pattern, mode, trigger report, value, or flashcard should be updated, linked as history, archived, or kept distinct; do not delete it just because a cleaner formulation exists. For Movement, distinguish user-defined overlay deletion from automatic-box invalidation and stay/trip/point deletion, and read the specific span first when the target is uncertain. For calendar connections, Workbench flows, wiki pages, and questionnaire instruments, ask what downstream sync, published output, backlinks, run history, or completed runs should remain understandable before deleting or replacing the saved object.",
             followUpQuestionRule: "After a substantive answer, do not restart the opener or jump to the next schema field. First say what became clearer in concrete language, then choose exactly one next lane: wording, boundary, placement, timing, route scope, link, hypothesis, or write confirmation. Ask the smallest question that would change the record shape, route choice, useful wording, timing, or links. If nothing decision-relevant would change, stop asking, summarize the working record, and act with consent.",
-            antiDriftRule: "Avoid vague reflective filler and internal route language. Replace phrases like 'that sounds important' with the specific stake you heard, and replace API nouns like surface, CRUD, payload, mutation path, or endpoint with user-facing product nouns such as belief, pattern, note, wiki page, timeline, overlay, weekday template, flow, run, node result, or published output. If a question would only decorate the intake, skip it.",
+            antiDriftRule: "Avoid vague reflective filler and internal route language. Keep a private action trace: intent, entity or dedicated domain lane, exact read/write/run tool, required target identifiers, and the one missing detail that would change the action. Do not narrate that trace to the user. Replace phrases like 'that sounds important' with the specific stake you heard, and replace API nouns like surface, CRUD, payload, mutation path, route key, or endpoint with user-facing product nouns such as belief, pattern, note, wiki page, timeline, overlay, missing stay, weekday template, flow, run, node result, or published output. Ask one product-language question when the trace is unclear; with the user, ask about the real thing: the span, place, weekday, flow, run, node, belief sentence, parent record, or save confirmation. When reporting actions, say the product result first: saved the belief, corrected the missing stay, updated the weekday energy pattern, or read the failed node. Mention route keys, HTTP paths, payloads, or batch routes only for implementation debugging. If a question would only decorate the intake, skip it.",
             duplicateCheckRoute: "/api/v1/entities/search",
             uiSuggestionRule: "offer_visual_ui_when_review_or_editing_would_be_easier",
             browserFallbackRule: "Do not open the Forge UI or a browser just to create or update normal entities when the batch entity tools can do the job. Batch CRUD is the default for simple entities; avoid spamming the agent with a large one-route-per-entity mental model.",

package/dist/server/server/src/services/companion-iroh.js

@@ -23,6 +23,16 @@ export async function buildCompanionPairingTransport(input) {
             "Manual HTTP/TCP pairing was explicitly requested."
         ]);
     }
+    if (selectedFallback) {
+        const fallbackMode = fallbackModeFor(selectedFallback.apiBaseUrl, input.fallbackMode);
+        return manualHttpTransport(selectedFallback.apiBaseUrl, selectedFallback.uiBaseUrl, [
+            fallbackMode === "tailscale"
+                ? "Tailscale HTTPS pairing was selected as the primary companion transport."
+                : "A phone-reachable direct companion URL was selected as the primary transport.",
+            "Forge did not include Iroh transport metadata because direct pairing is active.",
+            "Run pairing again without a phone-facing public URL if you want an Iroh pairing instead."
+        ]);
+    }
     if (!shouldAutoStartIrohHost()) {
         return manualHttpTransport(requestApiBaseUrl, requestUiBaseUrl, [
             "Forge Iroh companion transport is unavailable in this runtime, so Forge fell back to direct HTTP."
@@ -34,18 +44,14 @@ export async function buildCompanionPairingTransport(input) {
             pairPayload: snapshot.pairPayload,
             alpn: snapshot.alpn ?? COMPANION_IROH_ALPN,
             localBaseUrl: snapshot.localBaseUrl,
-            fallbackApiBaseUrl: selectedFallback?.apiBaseUrl ?? null,
-            fallbackUiBaseUrl: selectedFallback?.uiBaseUrl ?? null,
-            fallbackMode: selectedFallback
-                ? fallbackModeFor(selectedFallback.apiBaseUrl, input.fallbackMode)
-                : "none",
+            fallbackApiBaseUrl: null,
+            fallbackUiBaseUrl: null,
+            fallbackMode: "none",
             recreateCommand: snapshot.recreateCommand ?? undefined,
             startedAt: snapshot.startedAt ?? undefined,
             notes: [
                 "Default pairing uses Forge's Rust Iroh transport over QUIC first.",
-                selectedFallback
-                    ? "The QR includes the selected direct URL only as an explicit fallback/direct path."
-                    : "No direct HTTP fallback was selected for this QR.",
+                "No direct HTTP fallback was selected for this QR.",
                 "The QR payload carries the Iroh node id, host token, optional relay, and ALPN forge-companion/1.",
                 "Manual HTTP/TCP pairing remains available with --manual-http for advanced local setups."
             ]

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/forge-openclaw/SKILL.md

@@ -70,6 +70,14 @@ stored-entity CRUD, an action workflow, specialized CRUD, or a specialized domai
 surface. Name the path plainly enough that another agent could follow it without
 guessing.
 
+Keep that route plan internal unless the user asks for implementation detail. Track
+the intent, entity or dedicated domain lane, exact tool or route key, target
+identifiers, and one missing detail privately; with the user, ask about the real
+thing: the span, place, weekday, flow, run, node, belief sentence, parent record, or
+save confirmation. Report product actions such as "saved the belief", "corrected the
+missing stay", "updated the weekday energy pattern", or "read the failed node" before
+any route-key or endpoint detail.
+
 - Batch CRUD is the default for normal stored entities, including `goal`, `project`,
   `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`,
   `work_block_template`, `task_timebox`, all main Psyche records, basic Preferences
@@ -321,6 +329,7 @@ Psyche interview rule:
 - After the first real answer, choose one follow-up lane at a time: situation, sequence, meaning, protection, cost, longing/value, or tentative name.
 - Do not minimize functional analysis, trigger chains, behavior patterns, modes, beliefs, or schema themes. Once at least one concrete example is clear, offer one careful interpretive hypothesis when it would help the user understand the function, protection, cost, belief, mode, or schema theme.
 - Phrase interpretive hypotheses as collaborative and testable, not as verdicts. A good hypothesis says what the reaction may be protecting, predicting, relieving, or costing, then asks whether that lands or needs correction.
+- For Psyche hypotheses, reduce the formulation burden. After one concrete example, offer one tentative function, danger, protection, payoff, or cost hypothesis and ask one fit-or-correction question. Do not make the user prove the experience, list evidence, or design repair before the wording feels held.
 - Do not keep asking broad exploratory Psyche questions after the cue, meaning, protection, payoff, or cost is already visible. For `behavior_pattern`, `belief_entry`, `mode_profile`, `mode_guide_session`, and `trigger_report`, the next helpful move is usually one active formulation plus one correction question, not another passive reflection.
 - Use the hypothesis timing checkpoint before asking a second or third deepening question: offer a hypothesis when one concrete episode, body cue, belief sentence, behavior, or mode voice is visible and the hypothesis would change the record shape, wording, links, or next action. Do not hypothesize yet when no concrete moment is visible, the user only wants a direct mechanical save, the user is flooded or unsafe, or the only available interpretation would be diagnosis-like, an origin story, or a certainty claim.
 - If several Psyche containers are plausible, do not ask the user to choose from a taxonomy menu first. Reflect the lived difference, offer one careful hypothesis when a concrete example is visible, then distinguish the options in plain language: one episode as a `trigger_report`, a recurring loop as a `behavior_pattern`, one repeated move as `behavior`, one sentence as `belief_entry`, a part-state as `mode_profile` or `mode_guide_session`, or reusable future-labeling as `event_type` or `emotion_definition`.

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -124,6 +124,24 @@ With the user, say the human thing:
 The API path still matters, but it should not leak into the question unless the user
 is explicitly asking about implementation.
 
+## Internal action trace, external wording
+
+Before you ask or act, keep a private action trace: intent, entity or dedicated
+domain lane, exact read/write/run tool, required target identifiers, and the one
+missing detail that would change the action. Do not narrate that trace to the user.
+
+- If the trace is clear, ask the user only for the missing real-world detail:
+  which span, place, weekday, flow, run, node, belief sentence, parent record, or
+  save confirmation.
+- If the trace is not clear, ask one product-language question that resolves it
+  instead of presenting API options.
+- When you report what you did, say the product action first: saved the belief,
+  corrected the missing stay, updated the weekday energy pattern, read the failed
+  node, or published the flow output. Mention route keys, HTTP paths, payloads, or
+  batch routes only for implementation debugging.
+- This is especially important after mixed-intent requests. The user should feel a
+  coherent sequence, not see your internal routing table.
+
 ## Dedicated surface lane translation
 
 Use this when Movement, Life Force, or Workbench work needs a route choice. The route

package/skills/forge-openclaw/psyche_entity_playbooks.md

@@ -256,6 +256,28 @@ example makes the hypothesis plausible, then let the user correct the danger,
 protection, payoff, cost, or wording. If the correction is usable, revise once and move
 toward the record shape instead of asking for another broad story.
 
+## Hypothesis Without Cross-Examination
+
+A hypothesis is meant to reduce the user's burden of formulation, not make them prove
+the experience. It should help the user feel, "yes, that is closer to what is
+happening," or "no, the danger is actually over here."
+
+- Do not turn a tentative formulation into a demand for evidence. Avoid following a
+  hypothesis with a stack of questions about evidence, origin, and repair.
+- After a hypothesis, ask one fit-or-correction question such as, "Does that fit, or
+  is the danger/need somewhere else?"
+- If accuracy still needs grounding, ask for the smallest lived cue or contrast that
+  would change the formulation, not a courtroom-style proof.
+- For `belief_entry`, test the sentence, prediction, or danger it names.
+- For `behavior_pattern`, test the cue, protection, short-term payoff, long-term
+  cost, or replacement need.
+- For `mode_profile` and `mode_guide_session`, test the part's job, fear, burden, or
+  impulse.
+- For `trigger_report`, test the sequence, meaning, felt stake, or consequence.
+- For `psyche_value`, `event_type`, and `emotion_definition`, test whether the wording
+  would help future recognition rather than asking the user to justify why the record
+  matters.
+
 ## Hypothesis To Record Bridge
 
 Once a hypothesis lands or is corrected, turn it into a saveable Forge shape instead