[claude] Kimi & Perplexity as Visible Workshop Agents (#11) (#111)

Co-authored-by: Claude (Opus 4.6) <claude@hermes.local>
Co-committed-by: Claude (Opus 4.6) <claude@hermes.local>

artifacts/api-server/src/lib/event-bus.ts

@@ -21,7 +21,11 @@ export type CostEvent =
 export type CommentaryEvent =
   | { type: "agent_commentary"; agentId: string; jobId: string; text: string };
 
-export type BusEvent = JobEvent | SessionEvent | DebateEvent | CostEvent | CommentaryEvent;
+// External agent state changes (e.g. Kimi, Perplexity picking up or completing tasks)
+export type AgentExternalEvent =
+  | { type: "agent:external_state"; agentId: string; state: string; taskSummary?: string };
+
+export type BusEvent = JobEvent | SessionEvent | DebateEvent | CostEvent | CommentaryEvent | AgentExternalEvent;
 
 class EventBus extends EventEmitter {
   emit(event: "bus", data: BusEvent): boolean;

artifacts/api-server/src/lib/trust.ts

@@ -205,6 +205,29 @@ export class TrustService {
   verifyToken(token: string): { pubkey: string; expiry: number } | null {
     return verifyToken(token);
   }
+
+  // TEST-ONLY: apply one decay cycle immediately, ignoring time thresholds.
+  // Subtracts DECAY_PER_DAY (default 1) from the stored trust score and persists.
+  async decayOnce(pubkey: string): Promise<{ previousScore: number; newScore: number; newTier: TrustTier }> {
+    const identity = await this.getOrCreate(pubkey);
+    const previousScore = identity.trustScore;
+    const newScore = Math.max(0, previousScore - DECAY_PER_DAY);
+    const newTier = computeTier(newScore);
+
+    await db
+      .update(nostrIdentities)
+      .set({ trustScore: newScore, tier: newTier, updatedAt: new Date() })
+      .where(eq(nostrIdentities.pubkey, pubkey));
+
+    logger.info("trust: test decay applied", {
+      pubkey: pubkey.slice(0, 8),
+      previousScore,
+      newScore,
+      newTier,
+    });
+
+    return { previousScore, newScore, newTier };
+  }
 }
 
 export const trustService = new TrustService();

artifacts/api-server/src/lib/world-state.ts

@@ -16,7 +16,7 @@ const DEFAULT_TIMMY: TimmyState = {
 
 const _state: WorldState = {
   timmyState: { ...DEFAULT_TIMMY },
-  agentStates: { alpha: "idle", beta: "idle", gamma: "idle", delta: "idle" },
+  agentStates: { alpha: "idle", beta: "idle", gamma: "idle", delta: "idle", kimi: "idle", perplexity: "idle" },
   updatedAt: new Date().toISOString(),
 };
 
@@ -34,8 +34,10 @@ export function setAgentStateInWorld(agentId: string, agentState: string): void
   _deriveTimmy();
 }
 
+const WORKSHOP_AGENTS = ["alpha", "beta", "gamma", "delta"];
+
 function _deriveTimmy(): void {
-  const states = Object.values(_state.agentStates);
+  const states = WORKSHOP_AGENTS.map(id => _state.agentStates[id] ?? "idle");
   if (states.includes("working")) {
     _state.timmyState.activity = "working";
     _state.timmyState.mood = "focused";

artifacts/api-server/src/routes/events.ts

@@ -269,6 +269,21 @@ function translateEvent(ev: BusEvent): object | null {
         text: ev.text,
       };
 
+    // ── External agent state (Kimi, Perplexity) (#11) ─────────────────────────
+    case "agent:external_state": {
+      updateAgentWorld(ev.agentId, ev.state);
+      void logWorldEvent(
+        `agent:${ev.state}`,
+        `${ev.agentId} is now ${ev.state}${ev.taskSummary ? `: ${ev.taskSummary.slice(0, 80)}` : ""}`,
+        ev.agentId,
+      );
+      const msgs: object[] = [{ type: "agent_state", agentId: ev.agentId, state: ev.state }];
+      if (ev.taskSummary) {
+        msgs.push({ type: "agent_task_summary", agentId: ev.agentId, summary: ev.taskSummary });
+      }
+      return msgs;
+    }
+
     default:
       return null;
   }

artifacts/api-server/src/routes/identity.ts

@@ -2,7 +2,7 @@ import { Router, type Request, type Response } from "express";
 import { randomBytes, randomUUID } from "crypto";
 import { verifyEvent, validateEvent } from "nostr-tools";
 import { db, nostrTrustVouches, nostrIdentities, timmyNostrEvents } from "@workspace/db";
-import { eq, count } from "drizzle-orm";
+import { eq, count, desc } from "drizzle-orm";
 import { trustService } from "../lib/trust.js";
 import { timmyIdentityService } from "../lib/timmy-identity.js";
 import { makeLogger } from "../lib/logger.js";
@@ -406,4 +406,65 @@ router.get("/identity/me", async (req: Request, res: Response) => {
   }
 });
 
+// ── POST /identity/me/decay (TEST-ONLY — disabled in production) ──────────────
+// Applies one decay cycle to the authenticated identity immediately, without
+// the normal 30-day absence threshold. Useful in test suites.
+// Returns 404 in production (NODE_ENV === "production").
+
+router.post("/identity/me/decay", async (req: Request, res: Response) => {
+  if (process.env["NODE_ENV"] === "production") {
+    res.status(404).json({ error: "Not found" });
+    return;
+  }
+
+  const raw = req.headers["x-nostr-token"];
+  const token = typeof raw === "string" ? raw.trim() : null;
+
+  if (!token) {
+    res.status(401).json({ error: "Missing X-Nostr-Token header" });
+    return;
+  }
+
+  const parsed = trustService.verifyToken(token);
+  if (!parsed) {
+    res.status(401).json({ error: "Invalid or expired nostr_token" });
+    return;
+  }
+
+  try {
+    const result = await trustService.decayOnce(parsed.pubkey);
+    res.json({
+      pubkey: parsed.pubkey,
+      previousScore: result.previousScore,
+      newScore: result.newScore,
+      newTier: result.newTier,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err instanceof Error ? err.message : "Decay failed" });
+  }
+});
+
+// ── GET /identity/leaderboard ─────────────────────────────────────────────────
+// Returns the top 20 identities sorted by trust score descending.
+// Public endpoint — no authentication required.
+
+router.get("/identity/leaderboard", async (_req: Request, res: Response) => {
+  try {
+    const rows = await db
+      .select({
+        pubkey: nostrIdentities.pubkey,
+        trustScore: nostrIdentities.trustScore,
+        tier: nostrIdentities.tier,
+        interactionCount: nostrIdentities.interactionCount,
+      })
+      .from(nostrIdentities)
+      .orderBy(desc(nostrIdentities.trustScore))
+      .limit(20);
+
+    res.json(rows);
+  } catch (err) {
+    res.status(500).json({ error: err instanceof Error ? err.message : "Failed to fetch leaderboard" });
+  }
+});
+
 export default router;

artifacts/api-server/src/routes/testkit.ts

@@ -29,6 +29,12 @@ const router = Router();
  *              Guarded on stubMode=true; polls until state=provisioning|ready (20 s timeout).
  *  - T24 ADDED: costLedger completeness after job completion — 8 fields, honest-accounting
  *              invariant (actualAmountSats ≤ workAmountSats), refundState enum check.
+ *  - T41 ADDED: POST /api/jobs with valid Nostr token → nostrPubkey in response matches identity.
+ *  - T42 ADDED: POST /api/sessions with valid Nostr token → nostrPubkey in response matches identity.
+ *  - T43 ADDED: GET /identity/me returns full trust fields (tier, score, interactionCount).
+ *  - T44 ADDED: POST /identity/me/decay (test-only endpoint, 404 in prod) → score decremented.
+ *  - T45 ADDED: GET /identity/leaderboard → HTTP 200, array sorted by trustScore desc.
+ *              New endpoints identity/me/decay and identity/leaderboard added to identity.ts.
  */
 router.get("/testkit", (req: Request, res: Response) => {
   const proto =
@@ -1092,6 +1098,208 @@ NODESCRIPT
   fi
 fi
 
+# ===========================================================================
+# T41–T45 — Nostr identity lifecycle: token decorates jobs/sessions + trust ops
+# Requires node + nostr-tools (same guard as T36). All five tests share one
+# inline node script that performs the full lifecycle and emits a JSON blob.
+# ===========================================================================
+
+# ---------------------------------------------------------------------------
+# T41–T45 Preamble — ephemeral keypair → challenge → sign → verify → token
+# Then: create job, create session, GET /identity/me, decay, leaderboard.
+# ---------------------------------------------------------------------------
+NOSTR_LC_SKIP=false
+NOSTR_LC_OUT=""
+if ! command -v node >/dev/null 2>&1; then
+  NOSTR_LC_SKIP=true
+fi
+if [[ "\$NOSTR_LC_SKIP" == "false" ]]; then
+  NOSTR_LC_TMPFILE=\$(mktemp /tmp/nostr_lc_XXXXXX.cjs)
+  cat > "\$NOSTR_LC_TMPFILE" << 'NODESCRIPT'
+'use strict';
+const https = require('https');
+const http  = require('http');
+const BASE  = process.argv[2];
+let nt;
+const NOSTR_CJS = '/home/runner/workspace/artifacts/api-server/node_modules/nostr-tools/lib/cjs/index.js';
+try { nt = require('nostr-tools'); } catch (_) { try { nt = require(NOSTR_CJS); } catch (_) { process.stderr.write('nostr-tools not importable\n'); process.exit(1); } }
+const { generateSecretKey, getPublicKey, finalizeEvent } = nt;
+function request(url, opts, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const mod = u.protocol === 'https:' ? https : http;
+    const req = mod.request(u, opts, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    });
+    req.on('error', reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+async function main() {
+  const sk = generateSecretKey();
+  const pubkey = getPublicKey(sk);
+  // challenge → sign → verify
+  const chalRes = await request(BASE + '/api/identity/challenge', { method: 'POST', headers: { 'Content-Type': 'application/json' } }, '{}');
+  if (chalRes.status !== 200) { process.stderr.write('challenge failed: ' + chalRes.status + '\n'); process.exit(1); }
+  const { nonce } = JSON.parse(chalRes.body);
+  const event = finalizeEvent({ kind: 27235, content: nonce, tags: [], created_at: Math.floor(Date.now() / 1000) }, sk);
+  const verRes = await request(BASE + '/api/identity/verify', { method: 'POST', headers: { 'Content-Type': 'application/json' } }, JSON.stringify({ event }));
+  if (verRes.status !== 200) { process.stderr.write('verify failed: ' + verRes.status + ' ' + verRes.body + '\n'); process.exit(1); }
+  const { nostr_token: token } = JSON.parse(verRes.body);
+  // POST /jobs with Nostr token
+  const jobRes  = await request(BASE + '/api/jobs', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Nostr-Token': token } }, JSON.stringify({ request: 'T41 Nostr job test' }));
+  const jobBody = JSON.parse(jobRes.body);
+  const jobCode = jobRes.status;
+  const jobId   = jobBody.jobId || null;
+  const jobNpub = jobBody.nostrPubkey || null;
+  // POST /sessions with Nostr token
+  const sessRes  = await request(BASE + '/api/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Nostr-Token': token } }, JSON.stringify({ amount_sats: 200 }));
+  const sessBody = JSON.parse(sessRes.body);
+  const sessCode = sessRes.status;
+  const sessId   = sessBody.sessionId || null;
+  const sessNpub = sessBody.nostrPubkey || null;
+  // GET /identity/me
+  const meRes  = await request(BASE + '/api/identity/me', { method: 'GET', headers: { 'X-Nostr-Token': token } });
+  const meBody = JSON.parse(meRes.body);
+  const meScore  = meBody.trust ? meBody.trust.score  : null;
+  const meTier   = meBody.trust ? meBody.trust.tier   : null;
+  const meIcount = meBody.trust ? meBody.trust.interactionCount : null;
+  // POST /identity/me/decay (test-only; non-200 → skip T44 gracefully)
+  const decayRes  = await request(BASE + '/api/identity/me/decay', { method: 'POST', headers: { 'X-Nostr-Token': token } });
+  const decayBody = JSON.parse(decayRes.body);
+  const decayCode = decayRes.status;
+  const decayPrev = decayBody.previousScore !== undefined ? decayBody.previousScore : null;
+  const decayNew  = decayBody.newScore      !== undefined ? decayBody.newScore      : null;
+  // GET /identity/leaderboard
+  const lbRes    = await request(BASE + '/api/identity/leaderboard', { method: 'GET', headers: {} });
+  const lbCode   = lbRes.status;
+  let lbBody = [];
+  try { lbBody = JSON.parse(lbRes.body); } catch (_) {}
+  const lbIsArray = Array.isArray(lbBody);
+  const lbSorted  = lbIsArray && lbBody.length < 2 ? true :
+    lbIsArray && lbBody.every((v, i) => i === 0 || lbBody[i - 1].trustScore >= v.trustScore);
+  process.stdout.write(JSON.stringify({
+    pubkey, token,
+    jobCode, jobId, jobNpub,
+    sessCode, sessId, sessNpub,
+    meScore, meTier, meIcount,
+    decayCode, decayPrev, decayNew,
+    lbCode, lbIsArray, lbSorted,
+  }) + '\n');
+}
+main().catch(err => { process.stderr.write(String(err) + '\n'); process.exit(1); });
+NODESCRIPT
+
+  NOSTR_LC_EXIT=0
+  NOSTR_LC_OUT=\$(node "\$NOSTR_LC_TMPFILE" "\$BASE" 2>/dev/null) || NOSTR_LC_EXIT=\$?
+  rm -f "\$NOSTR_LC_TMPFILE"
+  if [[ \$NOSTR_LC_EXIT -ne 0 || -z "\$NOSTR_LC_OUT" ]]; then
+    NOSTR_LC_SKIP=true
+  fi
+fi
+
+# Helper: extract a field from NOSTR_LC_OUT
+_lc() { echo "\$NOSTR_LC_OUT" | jq -r ".\$1" 2>/dev/null || echo ""; }
+
+# ---------------------------------------------------------------------------
+# T41 — POST /jobs with valid Nostr token → nostrPubkey in response
+# ---------------------------------------------------------------------------
+sep "Test 41 — POST /jobs with Nostr token → nostrPubkey set"
+if [[ "\$NOSTR_LC_SKIP" == "true" ]]; then
+  note SKIP "node unavailable or lifecycle preamble failed — skipping T41"
+  SKIP=\$((SKIP+1))
+else
+  T41_CODE=\$(_lc jobCode); T41_NPUB=\$(_lc jobNpub); T41_PK=\$(_lc pubkey)
+  if [[ "\$T41_CODE" == "201" && -n "\$T41_NPUB" && "\$T41_NPUB" != "null" && "\$T41_NPUB" == "\$T41_PK" ]]; then
+    note PASS "HTTP 201, nostrPubkey=\${T41_NPUB:0:8}... matches token identity"
+    PASS=\$((PASS+1))
+  else
+    note FAIL "code=\$T41_CODE nostrPubkey='\$T41_NPUB' expected='\$T41_PK'"
+    FAIL=\$((FAIL+1))
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# T42 — POST /sessions with valid Nostr token → nostrPubkey in response
+# ---------------------------------------------------------------------------
+sep "Test 42 — POST /sessions with Nostr token → nostrPubkey set"
+if [[ "\$NOSTR_LC_SKIP" == "true" ]]; then
+  note SKIP "node unavailable or lifecycle preamble failed — skipping T42"
+  SKIP=\$((SKIP+1))
+else
+  T42_CODE=\$(_lc sessCode); T42_NPUB=\$(_lc sessNpub); T42_PK=\$(_lc pubkey)
+  if [[ "\$T42_CODE" == "201" && -n "\$T42_NPUB" && "\$T42_NPUB" != "null" && "\$T42_NPUB" == "\$T42_PK" ]]; then
+    note PASS "HTTP 201, nostrPubkey=\${T42_NPUB:0:8}... matches token identity"
+    PASS=\$((PASS+1))
+  else
+    note FAIL "code=\$T42_CODE nostrPubkey='\$T42_NPUB' expected='\$T42_PK'"
+    FAIL=\$((FAIL+1))
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# T43 — GET /identity/me returns full trust fields (tier, score, interactionCount)
+# ---------------------------------------------------------------------------
+sep "Test 43 — GET /identity/me returns tier + score + interactionCount"
+if [[ "\$NOSTR_LC_SKIP" == "true" ]]; then
+  note SKIP "node unavailable or lifecycle preamble failed — skipping T43"
+  SKIP=\$((SKIP+1))
+else
+  T43_TIER=\$(_lc meTier); T43_SCORE=\$(_lc meScore); T43_ICOUNT=\$(_lc meIcount)
+  if [[ -n "\$T43_TIER" && "\$T43_TIER" != "null" \
+      && "\$T43_SCORE" != "" && "\$T43_SCORE" != "null" \
+      && "\$T43_ICOUNT" != "" && "\$T43_ICOUNT" != "null" ]]; then
+    note PASS "tier=\$T43_TIER score=\$T43_SCORE interactionCount=\$T43_ICOUNT"
+    PASS=\$((PASS+1))
+  else
+    note FAIL "tier='\$T43_TIER' score='\$T43_SCORE' icount='\$T43_ICOUNT'"
+    FAIL=\$((FAIL+1))
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# T44 — POST /identity/me/decay (test-only endpoint) → score decremented
+# Skipped gracefully if endpoint returns non-200 (e.g., production mode).
+# ---------------------------------------------------------------------------
+sep "Test 44 — POST /identity/me/decay (test mode) → trust_score decremented"
+if [[ "\$NOSTR_LC_SKIP" == "true" ]]; then
+  note SKIP "node unavailable or lifecycle preamble failed — skipping T44"
+  SKIP=\$((SKIP+1))
+else
+  T44_CODE=\$(_lc decayCode); T44_PREV=\$(_lc decayPrev); T44_NEW=\$(_lc decayNew)
+  if [[ "\$T44_CODE" != "200" ]]; then
+    note SKIP "decay endpoint returned code=\$T44_CODE (not in test mode) — skipping T44"
+    SKIP=\$((SKIP+1))
+  elif [[ -n "\$T44_PREV" && -n "\$T44_NEW" && "\$T44_NEW" =~ ^[0-9]+\$ && "\$T44_PREV" =~ ^[0-9]+\$ && \$T44_NEW -le \$T44_PREV ]]; then
+    note PASS "previousScore=\$T44_PREV newScore=\$T44_NEW (decremented or floored at 0)"
+    PASS=\$((PASS+1))
+  else
+    note FAIL "code=\$T44_CODE previousScore='\$T44_PREV' newScore='\$T44_NEW' (expected new ≤ prev)"
+    FAIL=\$((FAIL+1))
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# T45 — GET /identity/leaderboard → HTTP 200, array sorted by trust score
+# ---------------------------------------------------------------------------
+sep "Test 45 — GET /identity/leaderboard → sorted array"
+if [[ "\$NOSTR_LC_SKIP" == "true" ]]; then
+  note SKIP "node unavailable or lifecycle preamble failed — skipping T45"
+  SKIP=\$((SKIP+1))
+else
+  T45_CODE=\$(_lc lbCode); T45_ARRAY=\$(_lc lbIsArray); T45_SORTED=\$(_lc lbSorted)
+  if [[ "\$T45_CODE" == "200" && "\$T45_ARRAY" == "true" && "\$T45_SORTED" == "true" ]]; then
+    note PASS "HTTP 200, array returned and sorted by trustScore desc"
+    PASS=\$((PASS+1))
+  else
+    note FAIL "code=\$T45_CODE isArray=\$T45_ARRAY sorted=\$T45_SORTED"
+    FAIL=\$((FAIL+1))
+  fi
+fi
+
 # ===========================================================================
 # FUTURE STUBS — placeholders for upcoming tasks (do not affect PASS/FAIL)
 # ===========================================================================

artifacts/mobile/app.json

@@ -20,7 +20,20 @@
       "adaptiveIcon": {
         "foregroundImage": "./assets/images/icon.png",
         "backgroundColor": "#0A0A12"
+      },
+      "intentFilters": [
+        {
+          "action": "VIEW",
+          "autoVerify": false,
+          "data": [
+            {
+              "scheme": "mobile",
+              "host": "nostr-callback"
             }
+          ],
+          "category": ["BROWSABLE", "DEFAULT"]
+        }
+      ]
     },
     "web": {
       "favicon": "./assets/images/icon.png",

artifacts/mobile/app/_layout.tsx

@@ -16,6 +16,7 @@ import { SafeAreaProvider } from "react-native-safe-area-context";
 
 import { ErrorBoundary } from "@/components/ErrorBoundary";
 import { TimmyProvider } from "@/context/TimmyContext";
+import { NostrProvider } from "@/context/NostrContext";
 import { ONBOARDING_COMPLETED_KEY } from "@/constants/storage-keys";
 
 SplashScreen.preventAutoHideAsync();
@@ -77,9 +78,11 @@ export default function RootLayout() {
         <QueryClientProvider client={queryClient}>
           <GestureHandlerRootView style={{ flex: 1 }}>
             <KeyboardProvider>
+              <NostrProvider>
                 <TimmyProvider>
                   <RootLayoutNav />
                 </TimmyProvider>
+              </NostrProvider>
             </KeyboardProvider>
           </GestureHandlerRootView>
         </QueryClientProvider>

artifacts/mobile/app/settings.tsx

@@ -1,114 +1,101 @@
-import { Stack } from 'expo-router';
+import { Stack } from "expo-router";
-import { View, Text, StyleSheet, ScrollView, TextInput, Switch, Pressable, Linking, Platform } from 'react-native';
+import {
-import { useState, useEffect } from 'react';
+  Linking,
-import AsyncStorage from '@react-native-async-storage/async-storage';
+  Platform,
-import * as SecureStore from 'expo-secure-store';
+  Pressable,
-import Constants from 'expo-constants';
+  ScrollView,
-import { useTimmy } from '@/context/TimmyContext';
+  StyleSheet,
-import { Ionicons } from '@expo/vector-icons';
+  Switch,
-import { ConnectionBadge } from '@/components/ConnectionBadge';
+  Text,
-import { Colors } from '@/constants/colors';
+  TextInput,
+  View,
+} from "react-native";
+import { useState, useEffect } from "react";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import Constants from "expo-constants";
+import { Ionicons } from "@expo/vector-icons";
 
-const STORAGE_KEYS = {
+import { useTimmy } from "@/context/TimmyContext";
-  SERVER_URL: 'settings_server_url',
+import { useNostr, truncateNpub } from "@/context/NostrContext";
-  NOTIFICATIONS_JOB_COMPLETION: 'settings_notifications_job_completion',
+import { ConnectionBadge } from "@/components/ConnectionBadge";
-  NOTIFICATIONS_LOW_BALANCE: 'settings_notifications_low_balance',
+import { NostrConnectModal } from "@/components/NostrConnectModal";
-  NOSTR_PRIVATE_KEY: 'settings_nostr_private_key', // Use SecureStore for this
+import { Colors } from "@/constants/colors";
-};
+
+const NOTIF_JOB_KEY = "settings.notifications_job_completion";
+const NOTIF_BALANCE_KEY = "settings.notifications_low_balance";
 
 export default function SettingsScreen() {
-  const { apiBaseUrl, setApiBaseUrl, isConnected, nostrPublicKey, connectNostr, disconnectNostr } = useTimmy();
   const C = Colors.dark;
+  const { apiBaseUrl, setApiBaseUrl, isConnected } = useTimmy();
+  const { npub, nostrConnected, signerType, disconnect: disconnectNostr } = useNostr();
 
   const [serverUrl, setServerUrl] = useState(apiBaseUrl);
   const [jobCompletionNotifications, setJobCompletionNotifications] = useState(false);
   const [lowBalanceWarning, setLowBalanceWarning] = useState(false);
-  const [currentNpub, setCurrentNpub] = useState<string | null>(nostrPublicKey);
+  const [nostrModalVisible, setNostrModalVisible] = useState(false);
+
+  // Sync local serverUrl with context value (e.g. on first load from AsyncStorage)
+  useEffect(() => {
+    setServerUrl(apiBaseUrl);
+  }, [apiBaseUrl]);
 
   useEffect(() => {
-    // Load settings from AsyncStorage and SecureStore
+    AsyncStorage.multiGet([NOTIF_JOB_KEY, NOTIF_BALANCE_KEY])
-    const loadSettings = async () => {
+      .then(([[, job], [, balance]]) => {
-      const storedServerUrl = await AsyncStorage.getItem(STORAGE_KEYS.SERVER_URL);
+        if (job !== null) setJobCompletionNotifications(JSON.parse(job));
-      if (storedServerUrl) {
+        if (balance !== null) setLowBalanceWarning(JSON.parse(balance));
-        setServerUrl(storedServerUrl);
+      })
-      }
+      .catch(() => {});
-      const storedJobCompletion = await AsyncStorage.getItem(STORAGE_KEYS.NOTIFICATIONS_JOB_COMPLETION);
+  }, []);
-      if (storedJobCompletion !== null) {
-        setJobCompletionNotifications(JSON.parse(storedJobCompletion));
-      }
-      const storedLowBalance = await AsyncStorage.getItem(STORAGE_KEYS.NOTIFICATIONS_LOW_BALANCE);
-      if (storedLowBalance !== null) {
-        setLowBalanceWarning(JSON.parse(storedLowBalance));
-      }
-      // Nostr npub is handled by TimmyContext, so we just use the provided nostrPublicKey
-      setCurrentNpub(nostrPublicKey);
-    };
-    loadSettings();
-  }, [nostrPublicKey]);
 
-  // Update apiBaseUrl in context when serverUrl changes and is saved
+  const handleServerUrlBlur = () => {
-  useEffect(() => {
     if (serverUrl !== apiBaseUrl) {
       setApiBaseUrl(serverUrl);
-      AsyncStorage.setItem(STORAGE_KEYS.SERVER_URL, serverUrl);
     }
-  }, [serverUrl, setApiBaseUrl, apiBaseUrl]);
-
-  const handleServerUrlChange = (text: string) => {
-    setServerUrl(text);
   };
 
-  const toggleJobCompletionNotifications = async () => {
+  const toggleJobCompletion = async () => {
-    const newValue = !jobCompletionNotifications;
+    const next = !jobCompletionNotifications;
-    setJobCompletionNotifications(newValue);
+    setJobCompletionNotifications(next);
-    await AsyncStorage.setItem(STORAGE_KEYS.NOTIFICATIONS_JOB_COMPLETION, JSON.stringify(newValue));
+    await AsyncStorage.setItem(NOTIF_JOB_KEY, JSON.stringify(next));
   };
 
-  const toggleLowBalanceWarning = async () => {
+  const toggleLowBalance = async () => {
-    const newValue = !lowBalanceWarning;
+    const next = !lowBalanceWarning;
-    setLowBalanceWarning(newValue);
+    setLowBalanceWarning(next);
-    await AsyncStorage.setItem(STORAGE_KEYS.NOTIFICATIONS_LOW_BALANCE, JSON.stringify(newValue));
+    await AsyncStorage.setItem(NOTIF_BALANCE_KEY, JSON.stringify(next));
-  };
-
-  const handleConnectNostr = async () => {
-    // This will ideally link to a dedicated Nostr connection flow
-    console.log('Connect Nostr button pressed');
-    // For now, simulate connection if not connected
-    if (!currentNpub) {
-      // This is a placeholder. Real implementation would involve generating/importing keys.
-      const simulatedNpub = 'npub1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';
-      connectNostr(simulatedNpub, 'private_key_placeholder'); // Pass a placeholder private key
-      setCurrentNpub(simulatedNpub);
-      // In a real app, the private key would be securely stored and managed by the context
-      // For now, just a placeholder to show connected state
-    }
   };
 
   const handleDisconnectNostr = async () => {
     await disconnectNostr();
-    setCurrentNpub(null);
   };
 
-  const appVersion = Constants.expoConfig?.version || 'N/A';
+  const appVersion = Constants.expoConfig?.version ?? "N/A";
-  const buildCommitHash = Constants.expoConfig?.extra?.gitCommitHash || 'N/A';
+  const buildCommitHash = Constants.expoConfig?.extra?.["gitCommitHash"] ?? "N/A";
-  const giteaRepoUrl = 'http://143.198.27.163:3000/replit/timmy-tower';
+  const giteaRepoUrl = "http://143.198.27.163:3000/replit/timmy-tower";
-
-  const openGiteaLink = () => {
-    Linking.openURL(giteaRepoUrl);
-  };
 
   return (
-    <View style={styles.container}>
+    <View style={[styles.container, { backgroundColor: C.background }]}>
-      <Stack.Screen options={{ title: 'Settings', headerShown: true, headerStyle: { backgroundColor: C.surface }, headerTintColor: C.text }} />
+      <Stack.Screen
+        options={{
+          title: "Settings",
+          headerShown: true,
+          headerStyle: { backgroundColor: C.surface },
+          headerTintColor: C.text,
+        }}
+      />
       <ScrollView contentContainerStyle={styles.scrollContent}>
-        <Text style={styles.sectionHeader}>Connection</Text>
+
+        {/* ── Connection ──────────────────────────────────────────────── */}
+        <Text style={[styles.sectionHeader, { color: C.text }]}>Connection</Text>
         <View style={styles.settingItem}>
-          <Text style={styles.settingLabel}>Server URL</Text>
+          <Text style={[styles.settingLabel, { color: C.text }]}>Server URL</Text>
           <View style={styles.serverUrlContainer}>
             <TextInput
-              style={[styles.input, { color: C.text, backgroundColor: C.field }]} // Apply text and background color from Colors
+              style={[styles.input, { color: C.text, backgroundColor: C.field, borderColor: C.border }]}
               value={serverUrl}
-              onChangeText={handleServerUrlChange}
+              onChangeText={setServerUrl}
+              onBlur={handleServerUrlBlur}
               placeholder="Enter server URL"
               placeholderTextColor={C.textMuted}
               autoCapitalize="none"
@@ -118,61 +105,100 @@ export default function SettingsScreen() {
           </View>
         </View>
 
-        <Text style={styles.sectionHeader}>Notifications</Text>
+        {/* ── Notifications ────────────────────────────────────────────── */}
-        <View style={styles.settingItem}>
+        <Text style={[styles.sectionHeader, { color: C.text }]}>Notifications</Text>
-          <Text style={styles.settingLabel}>Job Completion Push Notifications</Text>
+        <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
+          <Text style={[styles.settingLabel, { color: C.text }]}>Job Completion</Text>
           <Switch
             trackColor={{ false: C.surface, true: C.accentGlow }}
-            thumbColor={Platform.OS === 'android' ? C.text : ''}
+            thumbColor={Platform.OS === "android" ? C.text : ""}
             ios_backgroundColor={C.field}
-            onValueChange={toggleJobCompletionNotifications}
+            onValueChange={toggleJobCompletion}
             value={jobCompletionNotifications}
           />
         </View>
-        <View style={styles.settingItem}>
+        <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
-          <Text style={styles.settingLabel}>Low Balance Warning</Text>
+          <Text style={[styles.settingLabel, { color: C.text }]}>Low Balance Warning</Text>
           <Switch
             trackColor={{ false: C.surface, true: C.accentGlow }}
-            thumbColor={Platform.OS === 'android' ? C.text : ''}
+            thumbColor={Platform.OS === "android" ? C.text : ""}
             ios_backgroundColor={C.field}
-            onValueChange={toggleLowBalanceWarning}
+            onValueChange={toggleLowBalance}
             value={lowBalanceWarning}
           />
         </View>
 
-        <Text style={styles.sectionHeader}>Identity</Text>
+        {/* ── Nostr Identity ───────────────────────────────────────────── */}
-        <View style={styles.settingItem}>
+        <Text style={[styles.sectionHeader, { color: C.text }]}>Identity</Text>
-          <Text style={styles.settingLabel}>Nostr Public Key</Text>
+        <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
+          <Text style={[styles.settingLabel, { color: C.text }]}>Nostr Public Key</Text>
           <Text style={[styles.settingValue, { color: C.textMuted }]}>
-            {currentNpub ? `${currentNpub.substring(0, 10)}...${currentNpub.substring(currentNpub.length - 5)}` : 'Not connected'}
+            {npub ? truncateNpub(npub) : "Not connected"}
           </Text>
         </View>
+
+        {nostrConnected && signerType && (
+          <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
+            <Text style={[styles.settingLabel, { color: C.text }]}>Signer</Text>
+            <Text style={[styles.settingValue, { color: C.textSecondary }]}>
+              {signerType === "amber" ? "Amber (NIP-55)" : "nsec key"}
+            </Text>
+          </View>
+        )}
+
         <View style={styles.buttonContainer}>
-          {!currentNpub ? (
+          {!nostrConnected ? (
-            <Pressable onPress={handleConnectNostr} style={({ pressed }) => [styles.button, { backgroundColor: C.accent, opacity: pressed ? 0.8 : 1 }]}>
+            <Pressable
-              <Text style={[styles.buttonText, { color: C.textInverted }]}>Connect Nostr</Text>
+              onPress={() => setNostrModalVisible(true)}
+              style={({ pressed }) => [
+                styles.button,
+                { backgroundColor: C.accent, opacity: pressed ? 0.8 : 1 },
+              ]}
+            >
+              <Text style={[styles.buttonText, { color: C.textInverted }]}>
+                Connect Nostr Identity
+              </Text>
             </Pressable>
           ) : (
-            <Pressable onPress={handleDisconnectNostr} style={({ pressed }) => [styles.button, { backgroundColor: C.destructive, opacity: pressed ? 0.8 : 1 }]}>
+            <Pressable
-              <Text style={[styles.buttonText, { color: C.textInverted }]}>Disconnect Nostr</Text>
+              onPress={handleDisconnectNostr}
+              style={({ pressed }) => [
+                styles.button,
+                { backgroundColor: C.destructive, opacity: pressed ? 0.8 : 1 },
+              ]}
+            >
+              <Text style={[styles.buttonText, { color: C.textInverted }]}>
+                Disconnect Nostr
+              </Text>
             </Pressable>
           )}
         </View>
 
-        <Text style={styles.sectionHeader}>About</Text>
+        {/* ── About ───────────────────────────────────────────────────── */}
-        <View style={styles.settingItem}>
+        <Text style={[styles.sectionHeader, { color: C.text }]}>About</Text>
-          <Text style={styles.settingLabel}>App Version</Text>
+        <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
+          <Text style={[styles.settingLabel, { color: C.text }]}>App Version</Text>
           <Text style={[styles.settingValue, { color: C.text }]}>{appVersion}</Text>
         </View>
-        <View style={styles.settingItem}>
+        <View style={[styles.settingItem, { borderBottomColor: C.border }]}>
-          <Text style={styles.settingLabel}>Build Commit Hash</Text>
+          <Text style={[styles.settingLabel, { color: C.text }]}>Build Commit</Text>
           <Text style={[styles.settingValue, { color: C.text }]}>{buildCommitHash}</Text>
         </View>
-        <Pressable onPress={openGiteaLink} style={({ pressed }) => [styles.linkButton, { opacity: pressed ? 0.8 : 1 }]}>
+        <Pressable
+          onPress={() => Linking.openURL(giteaRepoUrl)}
+          style={({ pressed }) => [styles.linkButton, { opacity: pressed ? 0.8 : 1 }]}
+        >
           <Ionicons name="link" size={16} color={C.text} />
-          <Text style={[styles.linkButtonText, { color: C.link }]}>View project on Gitea</Text>
+          <Text style={[styles.linkButtonText, { color: C.link }]}>
+            View project on Gitea
+          </Text>
         </Pressable>
       </ScrollView>
+
+      <NostrConnectModal
+        visible={nostrModalVisible}
+        onClose={() => setNostrModalVisible(false)}
+      />
     </View>
   );
 }
@@ -180,7 +206,6 @@ export default function SettingsScreen() {
 const styles = StyleSheet.create({
   container: {
     flex: 1,
-    backgroundColor: Colors.dark.background, // Use background color from Colors
   },
   scrollContent: {
     padding: 20,
@@ -188,36 +213,35 @@ const styles = StyleSheet.create({
   },
   sectionHeader: {
     fontSize: 18,
-    fontWeight: 'bold',
+    fontWeight: "bold",
-    color: Colors.dark.text,
     marginTop: 20,
     marginBottom: 10,
   },
   settingItem: {
-    flexDirection: 'row',
+    flexDirection: "row",
-    justifyContent: 'space-between',
+    justifyContent: "space-between",
-    alignItems: 'center',
+    alignItems: "center",
     paddingVertical: 12,
     borderBottomWidth: 0.5,
-    borderBottomColor: Colors.dark.border,
   },
   settingLabel: {
     fontSize: 16,
-    color: Colors.dark.text,
     flex: 1,
   },
   settingValue: {
-    fontSize: 16,
+    fontSize: 14,
+    flexShrink: 1,
+    textAlign: "right",
+    marginLeft: 8,
   },
   serverUrlContainer: {
-    flexDirection: 'row',
+    flexDirection: "row",
-    alignItems: 'center',
+    alignItems: "center",
     flex: 2,
   },
   input: {
     flex: 1,
     borderWidth: 1,
-    borderColor: Colors.dark.border,
     borderRadius: 8,
     padding: 8,
     fontSize: 14,
@@ -225,7 +249,7 @@ const styles = StyleSheet.create({
   },
   buttonContainer: {
     marginTop: 20,
-    alignItems: 'flex-start',
+    alignItems: "flex-start",
   },
   button: {
     paddingVertical: 10,
@@ -234,11 +258,11 @@ const styles = StyleSheet.create({
   },
   buttonText: {
     fontSize: 16,
-    fontWeight: 'bold',
+    fontWeight: "bold",
   },
   linkButton: {
-    flexDirection: 'row',
+    flexDirection: "row",
-    alignItems: 'center',
+    alignItems: "center",
     marginTop: 15,
     paddingVertical: 8,
   },

artifacts/mobile/components/NostrConnectModal.tsx

@@ -0,0 +1,276 @@
+/**
+ * NostrConnectModal — UI for connecting a Nostr identity on mobile.
+ *
+ * Android: offers "Connect with Amber" (NIP-55) as the primary action,
+ *   with manual nsec entry as a secondary option.
+ * iOS / other: manual nsec entry only.
+ */
+
+import React, { useCallback, useState } from "react";
+import {
+  ActivityIndicator,
+  Modal,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+import { Ionicons } from "@expo/vector-icons";
+
+import { Colors } from "@/constants/colors";
+import { useNostr } from "@/context/NostrContext";
+
+// ─── Props ────────────────────────────────────────────────────────────────────
+
+type Props = {
+  visible: boolean;
+  onClose: () => void;
+};
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+export function NostrConnectModal({ visible, onClose }: Props) {
+  const C = Colors.dark;
+  const { connectWithAmber, connectWithNsec, canUseAmber } = useNostr();
+
+  const [showNsecForm, setShowNsecForm] = useState(!canUseAmber);
+  const [nsecInput, setNsecInput] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const handleClose = useCallback(() => {
+    setNsecInput("");
+    setError(null);
+    setShowNsecForm(!canUseAmber);
+    onClose();
+  }, [canUseAmber, onClose]);
+
+  const handleAmberPress = useCallback(async () => {
+    setError(null);
+    setLoading(true);
+    try {
+      await connectWithAmber();
+      // Amber opens; the result arrives via deep-link callback.
+      // Close the modal — NostrContext handles the incoming URL.
+      handleClose();
+    } finally {
+      setLoading(false);
+    }
+  }, [connectWithAmber, handleClose]);
+
+  const handleNsecConnect = useCallback(async () => {
+    if (!nsecInput.trim()) {
+      setError("Please enter your nsec key");
+      return;
+    }
+    setError(null);
+    setLoading(true);
+    const result = await connectWithNsec(nsecInput.trim());
+    setLoading(false);
+    if (result.success) {
+      handleClose();
+    } else {
+      setError(result.error);
+    }
+  }, [nsecInput, connectWithNsec, handleClose]);
+
+  return (
+    <Modal
+      visible={visible}
+      animationType="slide"
+      transparent
+      onRequestClose={handleClose}
+    >
+      <View style={styles.overlay}>
+        <View style={[styles.sheet, { backgroundColor: C.surface, borderColor: C.border }]}>
+          {/* Header */}
+          <View style={styles.header}>
+            <Text style={[styles.title, { color: C.text }]}>Connect Nostr Identity</Text>
+            <Pressable onPress={handleClose} hitSlop={12}>
+              <Ionicons name="close" size={22} color={C.textSecondary} />
+            </Pressable>
+          </View>
+
+          {/* Android: Amber option */}
+          {canUseAmber && !showNsecForm && (
+            <View style={styles.body}>
+              <Text style={[styles.description, { color: C.textSecondary }]}>
+                Connect using{" "}
+                <Text style={{ color: C.text, fontWeight: "600" }}>Amber</Text>{" "}
+                — your keys stay in Amber and are never exposed to this app.
+              </Text>
+
+              <Pressable
+                onPress={handleAmberPress}
+                disabled={loading}
+                style={({ pressed }) => [
+                  styles.primaryButton,
+                  { backgroundColor: C.accent, opacity: pressed || loading ? 0.75 : 1 },
+                ]}
+              >
+                {loading ? (
+                  <ActivityIndicator color={C.textInverted} />
+                ) : (
+                  <>
+                    <Ionicons name="shield-checkmark" size={18} color={C.textInverted} />
+                    <Text style={[styles.buttonText, { color: C.textInverted }]}>
+                      Connect with Amber
+                    </Text>
+                  </>
+                )}
+              </Pressable>
+
+              <Pressable
+                onPress={() => setShowNsecForm(true)}
+                style={styles.secondaryLink}
+              >
+                <Text style={[styles.secondaryLinkText, { color: C.link }]}>
+                  Enter nsec manually instead
+                </Text>
+              </Pressable>
+            </View>
+          )}
+
+          {/* nsec form */}
+          {showNsecForm && (
+            <View style={styles.body}>
+              {canUseAmber && (
+                <Pressable
+                  onPress={() => { setShowNsecForm(false); setError(null); }}
+                  style={styles.backLink}
+                >
+                  <Ionicons name="arrow-back" size={14} color={C.link} />
+                  <Text style={[styles.secondaryLinkText, { color: C.link }]}>
+                    Use Amber instead
+                  </Text>
+                </Pressable>
+              )}
+
+              <Text style={[styles.description, { color: C.textSecondary }]}>
+                Paste your{" "}
+                <Text style={{ color: C.text, fontWeight: "600" }}>nsec1…</Text>{" "}
+                private key. It will be stored only in the device secure keystore
+                and never logged or transmitted.
+              </Text>
+
+              <TextInput
+                style={[
+                  styles.input,
+                  {
+                    backgroundColor: C.field,
+                    color: C.text,
+                    borderColor: error ? C.destructive : C.border,
+                  },
+                ]}
+                placeholder="nsec1…"
+                placeholderTextColor={C.textMuted}
+                value={nsecInput}
+                onChangeText={(t) => { setNsecInput(t); setError(null); }}
+                autoCapitalize="none"
+                autoCorrect={false}
+                secureTextEntry
+                editable={!loading}
+              />
+
+              {error && (
+                <Text style={[styles.errorText, { color: C.destructive }]}>
+                  {error}
+                </Text>
+              )}
+
+              <Pressable
+                onPress={handleNsecConnect}
+                disabled={loading}
+                style={({ pressed }) => [
+                  styles.primaryButton,
+                  { backgroundColor: C.accent, opacity: pressed || loading ? 0.75 : 1 },
+                ]}
+              >
+                {loading ? (
+                  <ActivityIndicator color={C.textInverted} />
+                ) : (
+                  <Text style={[styles.buttonText, { color: C.textInverted }]}>
+                    Connect
+                  </Text>
+                )}
+              </Pressable>
+            </View>
+          )}
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    justifyContent: "flex-end",
+    backgroundColor: "rgba(0,0,0,0.6)",
+  },
+  sheet: {
+    borderTopLeftRadius: 20,
+    borderTopRightRadius: 20,
+    borderWidth: 1,
+    borderBottomWidth: 0,
+    paddingHorizontal: 24,
+    paddingTop: 20,
+    paddingBottom: Platform.OS === "ios" ? 40 : 24,
+  },
+  header: {
+    flexDirection: "row",
+    justifyContent: "space-between",
+    alignItems: "center",
+    marginBottom: 16,
+  },
+  title: {
+    fontSize: 18,
+    fontWeight: "700",
+  },
+  body: {
+    gap: 14,
+  },
+  description: {
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  primaryButton: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+    paddingVertical: 14,
+    borderRadius: 10,
+  },
+  buttonText: {
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  secondaryLink: {
+    alignItems: "center",
+    paddingVertical: 4,
+  },
+  secondaryLinkText: {
+    fontSize: 14,
+  },
+  backLink: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4,
+  },
+  input: {
+    borderWidth: 1,
+    borderRadius: 10,
+    paddingHorizontal: 14,
+    paddingVertical: 12,
+    fontSize: 14,
+    fontFamily: Platform.OS === "ios" ? "Courier" : "monospace",
+  },
+  errorText: {
+    fontSize: 13,
+  },
+});

artifacts/mobile/constants/colors.ts

@@ -29,6 +29,10 @@ export const Colors = {
     working: "#F59E0B",
     idle: "#6B7280",
     micActive: "#EF4444",
+    field: "#1A1A2E",
+    textInverted: "#0A0A12",
+    destructive: "#EF4444",
+    link: "#A78BFA",
   },
 } as const;
 

artifacts/mobile/constants/storage-keys.ts

@@ -1 +1,2 @@
 export const ONBOARDING_COMPLETED_KEY = "app.onboarding_completed";
+export const SERVER_URL_KEY = "settings.server_url";

artifacts/mobile/context/NostrContext.tsx

@@ -0,0 +1,274 @@
+/**
+ * NostrContext — Nostr identity management for mobile.
+ *
+ * Android: NIP-55 Amber deep-link signing (com.greenart7c3.nostrsigner).
+ *   Opens Amber via the `nostrsigner:` URI scheme to retrieve the user's
+ *   public key; falls back to the Play Store install prompt when Amber is
+ *   not installed.
+ *
+ * iOS / manual fallback: nsec paste-in stored exclusively in Expo SecureStore.
+ *   The raw key is NEVER written to AsyncStorage, Redux state, or logs.
+ */
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { Linking, Platform } from "react-native";
+import * as SecureStore from "expo-secure-store";
+import { getPublicKey, nip19 } from "nostr-tools";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type NostrSignerType = "amber" | "nsec" | null;
+
+export type NostrConnectResult =
+  | { success: true }
+  | { success: false; error: string };
+
+type NostrContextValue = {
+  /** bech32 public key (npub1…), null when no identity is loaded */
+  npub: string | null;
+  /** Raw hex public key, null when no identity is loaded */
+  pubkeyHex: string | null;
+  /** How the key was connected */
+  signerType: NostrSignerType;
+  /** True when an identity is loaded */
+  nostrConnected: boolean;
+  /** True only on Android — Amber integration available */
+  canUseAmber: boolean;
+  /** Android only: launch Amber to retrieve the user's public key */
+  connectWithAmber: () => Promise<void>;
+  /** Both platforms: validate & store an nsec; derive and cache the npub */
+  connectWithNsec: (nsec: string) => Promise<NostrConnectResult>;
+  /** Wipe all Nostr credentials from SecureStore and reset state */
+  disconnect: () => Promise<void>;
+};
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const SECURE_KEY_NSEC = "nostr.nsec";
+const SECURE_KEY_NPUB = "nostr.npub";
+const SECURE_KEY_SIGNER_TYPE = "nostr.signer_type";
+
+/** The deep-link scheme declared in app.json */
+const APP_SCHEME = "mobile";
+/** Path Amber will call back to with the pubkey result */
+const AMBER_CALLBACK_URL = `${APP_SCHEME}://nostr-callback`;
+const AMBER_PACKAGE = "com.greenart7c3.nostrsigner";
+const AMBER_PLAY_STORE_URL =
+  "https://play.google.com/store/apps/details?id=com.greenart7c3.nostrsigner";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Truncate an npub for display: "npub1abcde…xyz12" */
+export function truncateNpub(npub: string): string {
+  if (npub.length <= 20) return npub;
+  return `${npub.substring(0, 10)}…${npub.substring(npub.length - 5)}`;
+}
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+const NostrContext = createContext<NostrContextValue | null>(null);
+
+export function NostrProvider({ children }: { children: React.ReactNode }) {
+  const [npub, setNpub] = useState<string | null>(null);
+  const [pubkeyHex, setPubkeyHex] = useState<string | null>(null);
+  const [signerType, setSignerType] = useState<NostrSignerType>(null);
+
+  const canUseAmber = Platform.OS === "android";
+
+  // ── Load persisted identity on mount ──────────────────────────────────────
+
+  useEffect(() => {
+    async function loadIdentity() {
+      try {
+        const [storedNpub, storedSignerType] = await Promise.all([
+          SecureStore.getItemAsync(SECURE_KEY_NPUB),
+          SecureStore.getItemAsync(SECURE_KEY_SIGNER_TYPE),
+        ]);
+
+        if (storedNpub && storedSignerType) {
+          setNpub(storedNpub);
+          setSignerType(storedSignerType as NostrSignerType);
+          try {
+            const decoded = nip19.decode(storedNpub);
+            if (decoded.type === "npub") {
+              setPubkeyHex(decoded.data as string);
+            }
+          } catch {
+            // npub decode failure — identity still "connected", pubkeyHex stays null
+          }
+        }
+      } catch {
+        // SecureStore unavailable (e.g. web build) — proceed without identity
+      }
+    }
+    loadIdentity();
+  }, []);
+
+  // ── Handle Amber callback deep link (Android) ─────────────────────────────
+
+  useEffect(() => {
+    if (!canUseAmber) return;
+
+    function handleUrl({ url }: { url: string }) {
+      if (!url.startsWith(`${APP_SCHEME}://nostr-callback`)) return;
+
+      try {
+        // React Native's URL parsing is not available in all environments;
+        // parse manually to avoid importing a polyfill.
+        const queryStart = url.indexOf("?");
+        if (queryStart === -1) return;
+        const params = new URLSearchParams(url.slice(queryStart + 1));
+        const result = params.get("result");
+        if (!result) return;
+
+        // Amber returns the hex pubkey in `result`
+        let hexKey = result;
+        if (result.startsWith("npub1")) {
+          const decoded = nip19.decode(result);
+          if (decoded.type === "npub") hexKey = decoded.data as string;
+        }
+
+        const derivedNpub = nip19.npubEncode(hexKey);
+
+        // Persist — no private key stored for Amber flow
+        SecureStore.setItemAsync(SECURE_KEY_NPUB, derivedNpub).catch(() => {});
+        SecureStore.setItemAsync(SECURE_KEY_SIGNER_TYPE, "amber").catch(() => {});
+
+        setNpub(derivedNpub);
+        setPubkeyHex(hexKey);
+        setSignerType("amber");
+      } catch {
+        // Malformed callback — silently ignore
+      }
+    }
+
+    const subscription = Linking.addEventListener("url", handleUrl);
+    return () => subscription.remove();
+  }, [canUseAmber]);
+
+  // ── Actions ───────────────────────────────────────────────────────────────
+
+  const connectWithAmber = useCallback(async () => {
+    // NIP-55: request the user's public key from Amber
+    const amberUri = `nostrsigner:?type=get_public_key&compressionType=none&returnType=signature&callbackUrl=${encodeURIComponent(AMBER_CALLBACK_URL)}`;
+
+    let canOpen = false;
+    try {
+      canOpen = await Linking.canOpenURL(`nostrsigner:`);
+    } catch {
+      canOpen = false;
+    }
+
+    if (canOpen) {
+      await Linking.openURL(amberUri);
+    } else {
+      // Amber not installed — direct user to Play Store
+      await Linking.openURL(AMBER_PLAY_STORE_URL);
+    }
+  }, []);
+
+  const connectWithNsec = useCallback(
+    async (nsec: string): Promise<NostrConnectResult> => {
+      const trimmed = nsec.trim();
+
+      if (!trimmed.startsWith("nsec1")) {
+        return { success: false, error: "Key must start with nsec1" };
+      }
+
+      let decoded: ReturnType<typeof nip19.decode>;
+      try {
+        decoded = nip19.decode(trimmed);
+      } catch {
+        return { success: false, error: "Invalid bech32 encoding" };
+      }
+
+      if (decoded.type !== "nsec") {
+        return { success: false, error: "Not a valid nsec key" };
+      }
+
+      let hexPubkey: string;
+      try {
+        const sk = decoded.data as Uint8Array;
+        hexPubkey = getPublicKey(sk);
+      } catch {
+        return { success: false, error: "Could not derive public key" };
+      }
+
+      const derivedNpub = nip19.npubEncode(hexPubkey);
+
+      try {
+        // Store only in SecureStore — never AsyncStorage, never logs
+        await SecureStore.setItemAsync(SECURE_KEY_NSEC, trimmed);
+        await SecureStore.setItemAsync(SECURE_KEY_NPUB, derivedNpub);
+        await SecureStore.setItemAsync(SECURE_KEY_SIGNER_TYPE, "nsec");
+      } catch {
+        return { success: false, error: "Failed to store key securely" };
+      }
+
+      setNpub(derivedNpub);
+      setPubkeyHex(hexPubkey);
+      setSignerType("nsec");
+
+      return { success: true };
+    },
+    []
+  );
+
+  const disconnect = useCallback(async () => {
+    try {
+      await Promise.all([
+        SecureStore.deleteItemAsync(SECURE_KEY_NSEC),
+        SecureStore.deleteItemAsync(SECURE_KEY_NPUB),
+        SecureStore.deleteItemAsync(SECURE_KEY_SIGNER_TYPE),
+      ]);
+    } catch {
+      // Best-effort cleanup; reset state regardless
+    }
+    setNpub(null);
+    setPubkeyHex(null);
+    setSignerType(null);
+  }, []);
+
+  // ── Context value ─────────────────────────────────────────────────────────
+
+  const value = useMemo<NostrContextValue>(
+    () => ({
+      npub,
+      pubkeyHex,
+      signerType,
+      nostrConnected: npub !== null,
+      canUseAmber,
+      connectWithAmber,
+      connectWithNsec,
+      disconnect,
+    }),
+    [
+      npub,
+      pubkeyHex,
+      signerType,
+      canUseAmber,
+      connectWithAmber,
+      connectWithNsec,
+      disconnect,
+    ]
+  );
+
+  return (
+    <NostrContext.Provider value={value}>{children}</NostrContext.Provider>
+  );
+}
+
+export function useNostr(): NostrContextValue {
+  const ctx = useContext(NostrContext);
+  if (!ctx) throw new Error("useNostr must be used within NostrProvider");
+  return ctx;
+}
+
+export { AMBER_PACKAGE };

artifacts/mobile/context/TimmyContext.tsx

@@ -8,6 +8,9 @@ import React, {
   useState,
 } from "react";
 import { AppState, Platform } from "react-native";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+import { SERVER_URL_KEY } from "@/constants/storage-keys";
 
 export type TimmyMood = "idle" | "thinking" | "working" | "speaking";
 
@@ -22,33 +25,42 @@ export type WsEvent = {
   count?: number;
 };
 
-export type ConnectionStatus = "connecting" | "connected" | "disconnected" | "reconnecting" | "error";
+export type ConnectionStatus =
+  | "connecting"
+  | "connected"
+  | "disconnected"
+  | "reconnecting"
+  | "error";
 
 type TimmyContextValue = {
   timmyMood: TimmyMood;
   connectionStatus: ConnectionStatus;
+  /** True when the WebSocket is fully open */
+  isConnected: boolean;
   recentEvents: WsEvent[];
   send: (msg: object) => void;
   sendVisitorMessage: (text: string) => void;
   visitorId: string;
+  /** Current API / WebSocket base domain */
+  apiBaseUrl: string;
+  /** Persist a new base URL and reconnect the WebSocket */
+  setApiBaseUrl: (url: string) => void;
 };
 
 const TimmyContext = createContext<TimmyContextValue | null>(null);
 
 const MAX_EVENTS = 100;
-const BASE_URL = process.env.EXPO_PUBLIC_DOMAIN ?? "";
+const ENV_DOMAIN = process.env["EXPO_PUBLIC_DOMAIN"] ?? "";
 const VISITOR_ID =
   Date.now().toString() + Math.random().toString(36).substr(2, 9);
 
-function getWsUrl(): string {
+function buildWsUrl(domain: string): string {
-  let domain = BASE_URL;
+  let d = domain.trim();
-  if (!domain) {
+  if (!d) d = "localhost:8080";
-    domain = "localhost:8080";
+  d = d.replace(/^https?:\/\//, "");
-  }
+  d = d.replace(/\/$/, "");
-  domain = domain.replace(/^https?:\/\//, "");
+  const proto = d.startsWith("localhost") ? "ws" : "wss";
-  domain = domain.replace(/\/$/, "");
+  return `${proto}://${d}/api/ws`;
-  const proto = domain.startsWith("localhost") ? "ws" : "wss";
-  return `${proto}://${domain}/api/ws`;
 }
 
 function deriveMood(agentStates: Record<string, string>): TimmyMood {
@@ -63,10 +75,12 @@ function deriveMood(agentStates: Record<string, string>): TimmyMood {
 }
 
 export function TimmyProvider({ children }: { children: React.ReactNode }) {
+  const [apiBaseUrl, setApiBaseUrlState] = useState(ENV_DOMAIN);
   const [timmyMood, setTimmyMood] = useState<TimmyMood>("idle");
   const [connectionStatus, setConnectionStatus] =
     useState<ConnectionStatus>("connecting");
   const [recentEvents, setRecentEvents] = useState<WsEvent[]>([]);
+
   const wsRef = useRef<WebSocket | null>(null);
   const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const retryCountRef = useRef(0);
@@ -77,6 +91,32 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
     delta: "idle",
   });
   const speakingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Stable ref so WebSocket callbacks always read the current URL
+  const apiBaseUrlRef = useRef(apiBaseUrl);
+  // Stable refs to break the connectWs ↔ scheduleRetry circular dependency
+  const connectWsRef = useRef<() => void>(() => {});
+  const scheduleRetryRef = useRef<() => void>(() => {});
+
+  // ── Load persisted URL on mount ────────────────────────────────────────
+
+  useEffect(() => {
+    AsyncStorage.getItem(SERVER_URL_KEY)
+      .then((stored) => {
+        if (stored) {
+          setApiBaseUrlState(stored);
+          apiBaseUrlRef.current = stored;
+        }
+      })
+      .catch(() => {});
+  }, []);
+
+  const setApiBaseUrl = useCallback((url: string) => {
+    setApiBaseUrlState(url);
+    apiBaseUrlRef.current = url;
+    AsyncStorage.setItem(SERVER_URL_KEY, url).catch(() => {});
+  }, []);
+
+  // ── WebSocket helpers ──────────────────────────────────────────────────
 
   const addEvent = useCallback((evt: Omit<WsEvent, "id" | "timestamp">) => {
     const entry: WsEvent = {
@@ -94,14 +134,14 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
       wsRef.current.close();
       wsRef.current = null;
     }
-    const url = getWsUrl();
+    const url = buildWsUrl(apiBaseUrlRef.current);
     setConnectionStatus("connecting");
     let ws: WebSocket;
     try {
       ws = new WebSocket(url);
     } catch {
       setConnectionStatus("error");
-      scheduleRetry();
+      scheduleRetryRef.current();
       return;
     }
     wsRef.current = ws;
@@ -134,10 +174,7 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
 
       if (type === "world_state") {
         const states = (msg.agentStates as Record<string, string>) ?? {};
-        agentStatesRef.current = {
+        agentStatesRef.current = { ...agentStatesRef.current, ...states };
-          ...agentStatesRef.current,
-          ...states,
-        };
         setTimmyMood(deriveMood(agentStatesRef.current));
         return;
       }
@@ -187,7 +224,7 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
 
     ws.onclose = () => {
       setConnectionStatus("disconnected");
-      scheduleRetry();
+      scheduleRetryRef.current();
     };
 
     ws.onerror = () => {
@@ -200,9 +237,15 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
     const delay = Math.min(1000 * Math.pow(2, retryCountRef.current), 30000);
     retryCountRef.current += 1;
     retryTimerRef.current = setTimeout(() => {
-      connectWs();
+      connectWsRef.current();
     }, delay);
-  }, [connectWs]);
+  }, []);
+
+  // Keep the stable refs current after every render
+  connectWsRef.current = connectWs;
+  scheduleRetryRef.current = scheduleRetry;
+
+  // ── Initial connect ────────────────────────────────────────────────────
 
   useEffect(() => {
     connectWs();
@@ -216,7 +259,19 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
     };
   }, [connectWs]);
 
-  // AppState-aware WebSocket reconnect on foreground
+  // Reconnect when apiBaseUrl changes (skip the very first render)
+  const isFirstRenderRef = useRef(true);
+  useEffect(() => {
+    if (isFirstRenderRef.current) {
+      isFirstRenderRef.current = false;
+      return;
+    }
+    retryCountRef.current = 0;
+    connectWs();
+  }, [apiBaseUrl, connectWs]);
+
+  // ── AppState-aware reconnect on foreground ─────────────────────────────
+
   useEffect(() => {
     if (Platform.OS === "web") return;
 
@@ -229,20 +284,17 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
       const isNowActive = nextAppState === "active";
 
       if (wasBackground && isNowActive) {
-        // App returned to foreground — check if WS is still alive
         const ws = wsRef.current;
         if (!ws || ws.readyState !== WebSocket.OPEN) {
-          // Cancel any pending retry so we don't create duplicates
           if (retryTimerRef.current) {
             clearTimeout(retryTimerRef.current);
             retryTimerRef.current = null;
           }
           retryCountRef.current = 0;
           setConnectionStatus("reconnecting");
-          connectWs();
+          connectWsRef.current();
         }
       } else if (nextAppState === "background") {
-        // Proactively close the WS to avoid OS killing it mid-frame
         if (retryTimerRef.current) {
           clearTimeout(retryTimerRef.current);
           retryTimerRef.current = null;
@@ -262,7 +314,9 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
     return () => {
       subscription.remove();
     };
-  }, [connectWs]);
+  }, []);
+
+  // ── Outbound messages ──────────────────────────────────────────────────
 
   const send = useCallback((msg: object) => {
     if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
@@ -270,28 +324,42 @@ export function TimmyProvider({ children }: { children: React.ReactNode }) {
     }
   }, []);
 
-  const sendVisitorMessage = useCallback(
+  const sendVisitorMessage = useCallback((text: string) => {
-    (text: string) => {
     if (wsRef.current && wsRef.current.readyState === WebSocket.OPEN) {
       wsRef.current.send(
-          JSON.stringify({ type: "visitor_message", visitorId: VISITOR_ID, text })
+        JSON.stringify({
+          type: "visitor_message",
+          visitorId: VISITOR_ID,
+          text,
+        })
       );
       setTimmyMood("thinking");
     }
-    },
+  }, []);
-    []
-  );
 
-  const value = useMemo(
+  // ── Context value ──────────────────────────────────────────────────────
+
+  const value = useMemo<TimmyContextValue>(
     () => ({
+      timmyMood,
+      connectionStatus,
+      isConnected: connectionStatus === "connected",
+      recentEvents,
+      send,
+      sendVisitorMessage,
+      visitorId: VISITOR_ID,
+      apiBaseUrl,
+      setApiBaseUrl,
+    }),
+    [
       timmyMood,
       connectionStatus,
       recentEvents,
       send,
       sendVisitorMessage,
-      visitorId: VISITOR_ID,
+      apiBaseUrl,
-    }),
+      setApiBaseUrl,
-    [timmyMood, connectionStatus, recentEvents, send, sendVisitorMessage]
+    ]
   );
 
   return (

artifacts/mobile/package.json

@@ -57,7 +57,9 @@
   },
   "dependencies": {
     "@react-native-voice/voice": "^3.2.4",
+    "expo-secure-store": "~14.0.1",
     "expo-speech": "^14.0.8",
+    "nostr-tools": "^2.23.3",
     "react-native-qrcode-svg": "^6.3.21",
     "react-native-webview": "^13.15.0"
   }

the-matrix/index.html

@@ -599,6 +599,109 @@
       #activity-heatmap #heatmap-bar { display: none; }
       #heatmap-icon-btn { display: block; }
     }
+
+    /* ── History button ──────────────────────────────────────────────── */
+    #open-history-btn {
+      font-family: 'Courier New', monospace; font-size: 11px; font-weight: bold;
+      color: #aabbdd; background: rgba(20, 16, 50, 0.85); border: 1px solid #2a2a44;
+      padding: 7px 18px; cursor: pointer; letter-spacing: 2px;
+      box-shadow: 0 0 14px #2244aa22;
+      transition: background 0.15s, box-shadow 0.15s, color 0.15s;
+      border-radius: 2px;
+      min-height: 36px;
+    }
+    #open-history-btn:hover, #open-history-btn:active {
+      background: rgba(35, 28, 80, 0.95);
+      box-shadow: 0 0 20px #3355aa44;
+      color: #ccddff;
+    }
+
+    /* ── History panel (bottom sheet) ───────────────────────────────── */
+    #history-panel {
+      position: fixed; bottom: -100%; left: 0; right: 0;
+      height: 70vh;
+      background: rgba(5, 3, 12, 0.97);
+      border-top: 1px solid #1a1a2e;
+      z-index: 100;
+      font-family: 'Courier New', monospace;
+      transition: bottom 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+      box-shadow: 0 -8px 32px rgba(40, 60, 120, 0.18);
+      display: flex; flex-direction: column;
+    }
+    #history-panel.open { bottom: 60px; }
+
+    .hist-header {
+      display: flex; align-items: center; gap: 8px;
+      padding: 14px 20px 10px;
+      border-bottom: 1px solid #1a1a2e;
+      font-size: 12px; letter-spacing: 3px; color: #5577aa;
+      flex-shrink: 0;
+    }
+    .hist-header span { flex: 1; text-shadow: 0 0 8px #2244aa66; }
+    #history-refresh-btn, #history-close {
+      background: transparent; border: 1px solid #1a1a2e;
+      color: #334466; font-family: 'Courier New', monospace;
+      font-size: 11px; padding: 3px 10px; cursor: pointer;
+      transition: color 0.2s, border-color 0.2s; letter-spacing: 1px;
+      border-radius: 2px;
+    }
+    #history-refresh-btn:hover { color: #5577aa; border-color: #334466; }
+    #history-refresh-btn:disabled { opacity: 0.4; cursor: default; }
+    #history-close { font-size: 14px; padding: 3px 8px; }
+    #history-close:hover { color: #6688bb; border-color: #4466aa; }
+
+    #history-list {
+      flex: 1; overflow-y: auto; padding: 12px 16px;
+      overscroll-behavior: contain;
+    }
+
+    .hist-empty {
+      color: #334466; font-size: 11px; letter-spacing: 1px;
+      line-height: 1.8; text-align: center;
+      margin-top: 40px; padding: 0 20px;
+    }
+
+    .hist-row {
+      border: 1px solid #1a1a2e; border-radius: 2px;
+      margin-bottom: 10px; overflow: hidden;
+      background: #060310;
+    }
+    .hist-row.hist-rejected { border-color: #331111; }
+    .hist-row-header {
+      padding: 10px 12px; cursor: pointer;
+      transition: background 0.15s;
+    }
+    .hist-row-header:hover { background: rgba(30, 25, 60, 0.6); }
+    .hist-prompt {
+      color: #aabbdd; font-size: 12px; line-height: 1.5;
+      display: -webkit-box; -webkit-line-clamp: 2;
+      -webkit-box-orient: vertical; overflow: hidden;
+      margin-bottom: 6px;
+    }
+    .hist-meta {
+      display: flex; gap: 12px; align-items: center;
+    }
+    .hist-cost { font-size: 10px; color: #ffcc44; letter-spacing: 1px; }
+    .hist-rejected .hist-cost { color: #994444; }
+    .hist-time { font-size: 10px; color: #334466; letter-spacing: 0.5px; flex: 1; }
+    .hist-chevron { font-size: 10px; color: #334466; transition: color 0.15s; }
+    .hist-row-header:hover .hist-chevron { color: #5577aa; }
+
+    .hist-row-body {
+      max-height: 0; overflow: hidden;
+      transition: max-height 0.3s ease-out;
+    }
+    .hist-row.expanded .hist-row-body {
+      max-height: 400px;
+      border-top: 1px solid #1a1a2e;
+    }
+    .hist-result {
+      color: #aabbdd; font-family: 'Courier New', monospace;
+      font-size: 11px; line-height: 1.6;
+      white-space: pre-wrap; word-break: break-word;
+      padding: 12px; margin: 0;
+      max-height: 400px; overflow-y: auto;
+    }
   </style>
 </head>
 <body>
@@ -640,6 +743,7 @@
   <div id="top-buttons">
     <button id="open-panel-btn">⚡ SUBMIT JOB</button>
     <button id="open-session-btn">⚡ FUND SESSION</button>
+    <button id="open-history-btn">⏱ HISTORY</button>
     <a id="relay-admin-btn" href="/admin/relay">⚙ RELAY ADMIN</a>
   </div>
 
@@ -789,6 +893,16 @@
     <div id="session-error"></div>
   </div>
 
+  <!-- ── History panel (bottom sheet) ─────────────────────────────── -->
+  <div id="history-panel">
+    <div class="hist-header">
+      <span>⏱ JOB HISTORY</span>
+      <button id="history-refresh-btn">↺ REFRESH</button>
+      <button id="history-close">✕</button>
+    </div>
+    <div id="history-list"></div>
+  </div>
+
   <!-- ── FPS crosshair ─────────────────────────────────────────────── -->
   <div id="crosshair"></div>
 

the-matrix/js/agent-defs.js

@@ -9,6 +9,7 @@
  *   label          — display name shown in the 3D HUD and chat panel
  *   color          — hex integer (0xRRGGBB) used for Three.js materials and lights
  *   role           — human-readable role string shown under the label sprite
+ *   specialization — optional capability description shown in agent inspect card
  *   direction      — cardinal facing direction (for future mesh orientation use)
  *   x, z           — world-space position on the horizontal plane (y is always 0)
  */
@@ -17,6 +18,14 @@ export const AGENT_DEFS = [
   { id: 'beta',  label: 'BETA',  color: 0x00aaff, role: 'worker',       direction: 'east',  x:  6, z:  0 },
   { id: 'gamma', label: 'GAMMA', color: 0xff6600, role: 'validator',    direction: 'south', x:  0, z:  6 },
   { id: 'delta', label: 'DELTA', color: 0xaa00ff, role: 'monitor',      direction: 'west',  x: -6, z:  0 },
+  {
+    id: 'kimi', label: 'KIMI', color: 0x00d4ff, role: 'analyst',
+    specialization: 'Long Context Analysis', direction: 'northwest', x: -10, z: -10,
+  },
+  {
+    id: 'perplexity', label: 'PERPLEXITY', color: 0xff6b9d, role: 'researcher',
+    specialization: 'Real-time Research', direction: 'northeast', x: 10, z: -10,
+  },
 ];
 
 /**

the-matrix/js/agents.js

@@ -7,10 +7,13 @@ const CRYSTAL_POS = new THREE.Vector3(0.6, 1.15, -4.1);
 
 const agentStates = Object.fromEntries(AGENT_DEFS.map(d => [d.id, 'idle']));
 
+// Workshop agents that drive Timmy's mood (excludes external agents Kimi/Perplexity)
+const WORKSHOP_AGENT_IDS = ['alpha', 'beta', 'gamma', 'delta'];
+
 function deriveTimmyState() {
   if (agentStates.gamma === 'working') return 'working';
   if (agentStates.beta === 'thinking' || agentStates.alpha === 'thinking') return 'thinking';
-  if (Object.values(agentStates).some(s => s !== 'idle')) return 'active';
+  if (WORKSHOP_AGENT_IDS.some(id => agentStates[id] !== 'idle')) return 'active';
   return 'idle';
 }
 
@@ -97,9 +100,108 @@ function _pickMouthGeo(smileAmount) {
 
 // ── Build Timmy ───────────────────────────────────────────────────────────────
 
+// ── External agent bodies (Kimi, Perplexity) ──────────────────────────────────
+const _extBodies = {};
+
 export function initAgents(sceneRef) {
   scene = sceneRef;
   timmy = buildTimmy(scene);
+  _initKimiBody(scene);
+  _initPerplexityBody(scene);
+}
+
+function _initKimiBody(sc) {
+  const group = new THREE.Group();
+  group.position.set(-10, 1.2, -10);
+
+  const mat = new THREE.MeshStandardMaterial({
+    color: 0x00d4ff, emissive: 0x004466, emissiveIntensity: 0.4,
+    roughness: 0.15, metalness: 0.4,
+  });
+  const core = new THREE.Mesh(new THREE.OctahedronGeometry(0.38, 0), mat);
+  group.add(core);
+
+  const ringMat = new THREE.MeshStandardMaterial({
+    color: 0x00d4ff, emissive: 0x0088aa, emissiveIntensity: 0.6,
+    roughness: 0.1, metalness: 0.6, transparent: true, opacity: 0.7,
+  });
+  const ring1 = new THREE.Mesh(new THREE.TorusGeometry(0.60, 0.025, 6, 32), ringMat);
+  ring1.rotation.x = Math.PI / 3;
+  group.add(ring1);
+
+  const ring2 = new THREE.Mesh(new THREE.TorusGeometry(0.76, 0.018, 6, 32), ringMat.clone());
+  ring2.rotation.x = Math.PI / 2;
+  ring2.rotation.z = Math.PI / 4;
+  group.add(ring2);
+
+  const light = new THREE.PointLight(0x00d4ff, 0.5, 8);
+  group.add(light);
+
+  sc.add(group);
+  _extBodies.kimi = { group, core, ring1, ring2, light, mat, pulsePhase: Math.random() * Math.PI * 2 };
+}
+
+function _initPerplexityBody(sc) {
+  const group = new THREE.Group();
+  group.position.set(10, 1.2, -10);
+
+  const mat = new THREE.MeshStandardMaterial({
+    color: 0xff6b9d, emissive: 0x660033, emissiveIntensity: 0.4,
+    roughness: 0.2, metalness: 0.3,
+  });
+  const core = new THREE.Mesh(new THREE.IcosahedronGeometry(0.32, 0), mat);
+  group.add(core);
+
+  const scanMat = new THREE.MeshStandardMaterial({
+    color: 0xff6b9d, emissive: 0xaa2255, emissiveIntensity: 0.7,
+    roughness: 0.1, metalness: 0.5, transparent: true, opacity: 0.65,
+  });
+  const scanRings = [0, Math.PI / 3, -Math.PI / 3].map(angle => {
+    const r = new THREE.Mesh(new THREE.TorusGeometry(0.55, 0.022, 6, 28), scanMat.clone());
+    r.rotation.x = Math.PI / 2 + angle;
+    r.rotation.z = angle * 0.5;
+    group.add(r);
+    return r;
+  });
+
+  const light = new THREE.PointLight(0xff6b9d, 0.5, 8);
+  group.add(light);
+
+  sc.add(group);
+  _extBodies.perplexity = { group, core, scanRings, light, mat, pulsePhase: Math.random() * Math.PI * 2 };
+}
+
+function _updateExtBodies(t) {
+  _updateExtBody('kimi', t);
+  _updateExtBody('perplexity', t);
+}
+
+function _updateExtBody(id, t) {
+  const body = _extBodies[id];
+  if (!body) return;
+  const state = agentStates[id] || 'idle';
+  const isActive   = state === 'working' || state === 'active';
+  const isThinking = state === 'thinking';
+
+  const speedMult = isActive ? 2.5 : isThinking ? 1.5 : 0.6;
+  const emissI    = isActive ? 1.2 : isThinking ? 0.7 : 0.25;
+  const lightI    = isActive ? 1.2 : isThinking ? 0.6 : 0.2;
+  const bobAmp    = isActive ? 0.10 : 0.04;
+
+  body.group.position.y = 1.2 + Math.sin(t * 0.0008 + body.pulsePhase) * bobAmp;
+  body.mat.emissiveIntensity = emissI;
+  body.light.intensity = lightI;
+
+  if (id === 'kimi') {
+    body.core.rotation.y += 0.008 * speedMult;
+    body.core.rotation.x += 0.003 * speedMult;
+    body.ring1.rotation.z += 0.012 * speedMult;
+    body.ring2.rotation.x += 0.007 * speedMult;
+  } else {
+    body.core.rotation.y += 0.006 * speedMult;
+    body.core.rotation.z += 0.009 * speedMult;
+    body.scanRings.forEach((r, i) => { r.rotation.y += (0.015 + i * 0.008) * speedMult; });
+  }
 }
 
 function buildTimmy(sc) {
@@ -417,6 +519,7 @@ export function updateAgents(time) {
   const t = time * 0.001;
   const dt = _lastFrameTime > 0 ? Math.min((time - _lastFrameTime) * 0.001, 0.05) : 0.016;
   _lastFrameTime = time;
+  _updateExtBodies(time);
 
   const vs = deriveTimmyState();
   const pulse = Math.sin(t * 1.8 + timmy.pulsePhase);
@@ -889,5 +992,19 @@ export function disposeAgents() {
   timmy.bubbleTex?.dispose();
   timmy.bubbleMat?.dispose();
   timmy = null;
+
+  // Dispose external agent bodies
+  for (const body of Object.values(_extBodies)) {
+    body.group.traverse(obj => {
+      if (obj.geometry) obj.geometry.dispose();
+      if (obj.material) {
+        const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+        mats.forEach(m => m.dispose());
+      }
+    });
+    if (scene) scene.remove(body.group);
+  }
+  for (const k of Object.keys(_extBodies)) delete _extBodies[k];
+
   scene = null;
 }

the-matrix/js/history.js

@@ -0,0 +1,222 @@
+/**
+ * history.js — Job history panel for Timmy Tower Workshop.
+ *
+ * Persists completed jobs in localStorage and renders them in a
+ * bottom-sheet panel with expandable results and pull-to-refresh.
+ *
+ * Public API:
+ *   addHistoryEntry(entry)   — called by payment.js / session.js on completion
+ *   initHistoryPanel()       — wire up DOM (call once from main.js)
+ */
+
+const LS_KEY      = 'timmy_history_v1';
+const MAX_ENTRIES = 50;
+
+// ── Persistence ───────────────────────────────────────────────────────────────
+
+function _loadEntries() {
+  try {
+    const raw = localStorage.getItem(LS_KEY);
+    return raw ? JSON.parse(raw) : [];
+  } catch {
+    return [];
+  }
+}
+
+function _saveEntries(entries) {
+  try {
+    localStorage.setItem(LS_KEY, JSON.stringify(entries));
+  } catch { /* storage full — oldest already trimmed */ }
+}
+
+/**
+ * Record a completed job.
+ * @param {object} entry
+ * @param {string} entry.jobId
+ * @param {string} entry.request      — user prompt
+ * @param {number} entry.costSats     — sats charged (0 for free/session)
+ * @param {string} entry.result       — AI answer or rejection reason
+ * @param {string} entry.state        — 'complete' | 'rejected' | 'failed'
+ * @param {string} [entry.completedAt] — ISO timestamp (defaults to now)
+ */
+export function addHistoryEntry({ jobId, request, costSats, result, state, completedAt }) {
+  const entries = _loadEntries();
+  const entry = {
+    jobId:       jobId       ?? `local-${Date.now()}`,
+    request:     request     ?? '',
+    costSats:    costSats    ?? 0,
+    result:      result      ?? '',
+    state:       state       ?? 'complete',
+    completedAt: completedAt ?? new Date().toISOString(),
+  };
+  const idx = entries.findIndex(e => e.jobId === entry.jobId);
+  if (idx >= 0) {
+    entries[idx] = entry;
+  } else {
+    entries.unshift(entry); // newest first
+    if (entries.length > MAX_ENTRIES) entries.length = MAX_ENTRIES;
+  }
+  _saveEntries(entries);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _relativeTime(isoString) {
+  try {
+    const diff = Date.now() - new Date(isoString).getTime();
+    const secs = Math.floor(diff / 1000);
+    if (secs < 60)  return `${secs}s ago`;
+    const mins = Math.floor(secs / 60);
+    if (mins < 60)  return `${mins} min ago`;
+    const hrs  = Math.floor(mins / 60);
+    if (hrs  < 24)  return `${hrs}h ago`;
+    const days = Math.floor(hrs  / 24);
+    return `${days}d ago`;
+  } catch {
+    return '';
+  }
+}
+
+function _escHtml(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function _truncate(text, maxLen) {
+  if (!text) return '';
+  return text.length > maxLen ? text.slice(0, maxLen) + '…' : text;
+}
+
+// ── Rendering ─────────────────────────────────────────────────────────────────
+
+function _renderEntries(entries, container) {
+  container.innerHTML = '';
+
+  if (!entries.length) {
+    const empty = document.createElement('div');
+    empty.className = 'hist-empty';
+    empty.textContent = 'No completed jobs yet. Submit a job to see your history here.';
+    container.appendChild(empty);
+    return;
+  }
+
+  entries.forEach(entry => {
+    const row = document.createElement('div');
+    row.className = 'hist-row' + (entry.state === 'rejected' ? ' hist-rejected' : '');
+
+    // ── Header (always visible) ────────────────────────────────────────────
+    const header = document.createElement('div');
+    header.className = 'hist-row-header';
+
+    const promptEl = document.createElement('div');
+    promptEl.className = 'hist-prompt';
+    promptEl.textContent = _truncate(entry.request, 140);
+
+    const metaEl = document.createElement('div');
+    metaEl.className = 'hist-meta';
+
+    const costEl = document.createElement('span');
+    costEl.className = 'hist-cost';
+    if (entry.state === 'rejected') {
+      costEl.textContent = 'rejected';
+    } else if (entry.costSats > 0) {
+      costEl.textContent = `⚡ ${entry.costSats} sats`;
+    } else {
+      costEl.textContent = 'free';
+    }
+
+    const timeEl = document.createElement('span');
+    timeEl.className = 'hist-time';
+    timeEl.textContent = _relativeTime(entry.completedAt);
+
+    const chevronEl = document.createElement('span');
+    chevronEl.className = 'hist-chevron';
+    chevronEl.textContent = '▸';
+
+    metaEl.appendChild(costEl);
+    metaEl.appendChild(timeEl);
+    metaEl.appendChild(chevronEl);
+
+    header.appendChild(promptEl);
+    header.appendChild(metaEl);
+
+    // ── Body (expandable) ──────────────────────────────────────────────────
+    const body = document.createElement('div');
+    body.className = 'hist-row-body';
+
+    const pre = document.createElement('pre');
+    pre.className = 'hist-result';
+    pre.textContent = entry.result || '(no result)';
+    body.appendChild(pre);
+
+    // ── Toggle ─────────────────────────────────────────────────────────────
+    let expanded = false;
+    header.addEventListener('click', () => {
+      expanded = !expanded;
+      row.classList.toggle('expanded', expanded);
+      chevronEl.textContent = expanded ? '▾' : '▸';
+    });
+
+    row.appendChild(header);
+    row.appendChild(body);
+    container.appendChild(row);
+  });
+}
+
+// ── Panel state ───────────────────────────────────────────────────────────────
+
+let _panel      = null;
+let _list       = null;
+let _refreshBtn = null;
+
+function _open() {
+  if (!_panel) return;
+  _panel.classList.add('open');
+  _refresh();
+}
+
+function _close() {
+  _panel?.classList.remove('open');
+}
+
+function _refresh() {
+  if (!_list) return;
+  const entries = _loadEntries();
+  _renderEntries(entries, _list);
+  if (_refreshBtn) {
+    _refreshBtn.textContent = '↺ REFRESH';
+    _refreshBtn.disabled = false;
+  }
+}
+
+export function initHistoryPanel() {
+  _panel      = document.getElementById('history-panel');
+  _list       = document.getElementById('history-list');
+  _refreshBtn = document.getElementById('history-refresh-btn');
+  if (!_panel) return;
+
+  document.getElementById('open-history-btn')?.addEventListener('click', _open);
+  document.getElementById('history-close')?.addEventListener('click', _close);
+
+  if (_refreshBtn) {
+    _refreshBtn.addEventListener('click', () => {
+      _refreshBtn.textContent = '↺ …';
+      _refreshBtn.disabled = true;
+      setTimeout(_refresh, 150);
+    });
+  }
+
+  // Pull-to-refresh: detect downward drag when already scrolled to top
+  let _touchStartY = 0;
+  _list?.addEventListener('touchstart', e => {
+    _touchStartY = e.touches[0].clientY;
+  }, { passive: true });
+  _list?.addEventListener('touchend', e => {
+    const dy = e.changedTouches[0].clientY - _touchStartY;
+    if (dy > 60 && _list.scrollTop === 0) {
+      _refresh();
+    }
+  }, { passive: true });
+}

the-matrix/js/hud-labels.js

@@ -12,7 +12,12 @@
  */
 
 import * as THREE from 'three';
-import { colorToCss } from './agent-defs.js';
+import { colorToCss, AGENT_DEFS } from './agent-defs.js';
+
+// Specialization lookup built once from AGENT_DEFS
+const _specializations = Object.fromEntries(
+  AGENT_DEFS.filter(d => d.specialization).map(d => [d.id, d.specialization])
+);
 
 const _proj   = new THREE.Vector3();
 let   _camera = null;
@@ -20,6 +25,7 @@ let   _labels = [];    // { el, worldPos: THREE.Vector3, id }
 
 // ── State cache (updated from WS) ────────────────────────────────────────────
 const _states = {};
+const _lastTasks = {};
 
 // ── Inspect popup ─────────────────────────────────────────────────────────────
 let _inspectEl    = null;
@@ -100,6 +106,10 @@ function _makeLabel(container, id, name, role, color, worldPos) {
   return { el, worldPos, id, color };
 }
 
+export function setLabelLastTask(id, summary) {
+  _lastTasks[id] = summary;
+}
+
 export function setLabelState(id, state) {
   _states[id] = state;
   const entry = _labels.find(l => l.id === id);
@@ -118,13 +128,17 @@ export function showInspectPopup(id, screenX, screenY) {
 
   const state  = _states[id] || 'idle';
   const uptime = Math.floor(performance.now() / 1000);
+  const spec    = _specializations[id];
+  const lastTask = _lastTasks[id];
   _inspectEl.innerHTML = `
     <div style="color:${entry.color};font-weight:bold;letter-spacing:2px;font-size:12px;margin-bottom:6px;">
       ${id.toUpperCase()}
     </div>
+    ${spec ? `<div style="color:${entry.color}99;margin-bottom:4px;font-size:10px;letter-spacing:1px;">⬡ ${spec}</div>` : ''}
     <div style="color:#aaa;margin-bottom:2px;">state&nbsp;&nbsp;: <span style="color:${entry.color}">${state}</span></div>
     <div style="color:#aaa;margin-bottom:2px;">uptime : ${uptime}s</div>
-    <div style="color:#aaa;">network: <span style="color:#44ff88">connected</span></div>
+    <div style="color:#aaa;margin-bottom:2px;">network: <span style="color:#44ff88">connected</span></div>
+    ${lastTask ? `<div style="color:#888;font-size:9px;margin-top:4px;border-top:1px solid #333;padding-top:4px;">last: ${lastTask.slice(0, 60)}</div>` : ''}
   `;
   _inspectEl.style.left    = `${screenX}px`;
   _inspectEl.style.top     = `${screenY}px`;

the-matrix/js/main.js

@@ -11,6 +11,7 @@ import { initInteraction, disposeInteraction, registerSlapTarget } from './inter
 import { initWebSocket, getConnectionState, getJobCount } from './websocket.js';
 import { initPaymentPanel } from './payment.js';
 import { initSessionPanel } from './session.js';
+import { initHistoryPanel } from './history.js';
 import { initNostrIdentity } from './nostr-identity.js';
 import { warmup as warmupEdgeWorker, onReady as onEdgeWorkerReady } from './edge-worker-client.js';
 import { setEdgeWorkerReady } from './ui.js';
@@ -46,6 +47,7 @@ function buildWorld(firstInit, stateSnapshot) {
     initWebSocket(scene);
     initPaymentPanel();
     initSessionPanel();
+    initHistoryPanel();
     void initNostrIdentity('/api');
     warmupEdgeWorker();
     onEdgeWorkerReady(() => setEdgeWorkerReady());

the-matrix/js/payment.js

@@ -10,6 +10,7 @@
  */
 
 import { getOrRefreshToken } from './nostr-identity.js';
+import { addHistoryEntry } from './history.js';
 
 const API_BASE = '/api';
 const POLL_INTERVAL_MS = 2000;
@@ -18,6 +19,7 @@ const POLL_TIMEOUT_MS  = 60000;
 let panel = null;
 let closeBtn = null;
 let currentJobId = null;
+let currentRequest = '';
 let pollTimer = null;
 
 export function initPaymentPanel() {
@@ -96,6 +98,7 @@ async function submitJob() {
     if (!res.ok) { setError(data.error || 'Failed to create job.'); return; }
 
     currentJobId = data.jobId;
+    currentRequest = request;
     showEvalInvoice(data.evalInvoice);
   } catch (err) {
     setError('Network error: ' + err.message);
@@ -167,7 +170,7 @@ function startPolling() {
       const pollHeaders = token ? { 'X-Nostr-Token': token } : {};
       const res  = await fetch(`${API_BASE}/jobs/${currentJobId}`, { headers: pollHeaders });
       const data = await res.json();
-      const { state, workInvoice, result, reason } = data;
+      const { state, workInvoice, result, reason, costLedger, completedAt } = data;
 
       if (state === 'awaiting_work_payment' && workInvoice) {
         showWorkInvoice(workInvoice);
@@ -175,10 +178,26 @@ function startPolling() {
         return;
       }
       if (state === 'complete') {
+        addHistoryEntry({
+          jobId: currentJobId,
+          request: currentRequest,
+          costSats: costLedger?.workAmountSats ?? costLedger?.actualAmountSats ?? 0,
+          result,
+          state: 'complete',
+          completedAt: completedAt ?? new Date().toISOString(),
+        });
         showResult(result, 'complete');
         return;
       }
       if (state === 'rejected') {
+        addHistoryEntry({
+          jobId: currentJobId,
+          request: currentRequest,
+          costSats: 0,
+          result: reason,
+          state: 'rejected',
+          completedAt: completedAt ?? new Date().toISOString(),
+        });
         showResult(reason, 'rejected');
         return;
       }

the-matrix/js/session.js

@@ -16,6 +16,7 @@ import { setSpeechBubble, setMood } from './agents.js';
 import { appendSystemMessage, setSessionSendHandler, setInputBarSessionMode } from './ui.js';
 import { getOrRefreshToken } from './nostr-identity.js';
 import { sentiment } from './edge-worker-client.js';
+import { addHistoryEntry } from './history.js';
 
 const API          = '/api';
 const LS_KEY       = 'timmy_session_v1';
@@ -152,12 +153,21 @@ export async function sessionSendHandler(text) {
       return;
     }
 
+    const prevBalance = _balanceSats;
     _balanceSats  = data.balanceRemaining ?? 0;
     _sessionState = _balanceSats < MIN_BALANCE ? 'paused' : 'active';
     _saveToStorage();
     _applySessionUI();
 
     const reply = data.result || data.reason || '…';
+    const costSats = Math.max(0, prevBalance - _balanceSats);
+    addHistoryEntry({
+      request: text,
+      costSats,
+      result: reply,
+      state: data.reason && !data.result ? 'rejected' : 'complete',
+      completedAt: new Date().toISOString(),
+    });
     setSpeechBubble(reply);
     appendSystemMessage('Timmy: ' + reply.slice(0, 80));
 

the-matrix/js/websocket.js

@@ -3,7 +3,7 @@ import { scene } from './world.js'; // Import the scene
 import { setAgentState, setSpeechBubble, applyAgentStates, setMood, TIMMY_WORLD_POS } from './agents.js';
 import { appendSystemMessage, appendDebateMessage, showCostTicker, updateCostTicker } from './ui.js';
 import { sentiment } from './edge-worker-client.js';
-import { setLabelState } from './hud-labels.js';
+import { setLabelState, setLabelLastTask } from './hud-labels.js';
 import { createJobIndicator, dissolveJobIndicator } from './effects.js';
 import { getPubkey } from './nostr-identity.js';
 
@@ -122,11 +122,19 @@ function handleMessage(msg) {
       break;
     }
 
+    case 'agent_task_summary': {
+      if (msg.agentId && msg.summary) {
+        setLabelLastTask(msg.agentId, msg.summary);
+      }
+      break;
+    }
+
     case 'job_completed': {
       if (jobCount > 0) jobCount--;
       if (msg.agentId) {
         setAgentState(msg.agentId, 'idle');
         setLabelState(msg.agentId, 'idle');
+        setLabelLastTask(msg.agentId, `job ${(msg.jobId || '').slice(0, 8)} completed`);
       }
       appendSystemMessage(`job ${(msg.jobId || '').slice(0, 8)} complete`);