feat(10-02): add self-aware preamble + ContextBuilder.systemPrompt(for:)

Replaces the hardcoded "You are Jarvis, a personal macOS assistant."
literal at App/AppDelegate.swift:1265 with a locked self-aware preamble
emitted by AgentCore's new ContextBuilder. The preamble names Jarvis,
lists capabilities (mic, camera, speakers), names the seven introspection
tools (list_audio_devices, get_active_audio_route, get_self_state,
list_camera_devices, get_time, get_clipboard, run_applescript) so the
model has handles, and ends with "You are not a text-only assistant."
Closes the 2026-05-05 / 2026-05-06 user-quoted failure modes.

Implements:
- ContextBuilder.selfAwarePreamble: locked Swift string constant (D-13).
  No JSON file, no localization, no runtime mutation. Length ~660 chars,
  well under the 4096-char cache-eligibility boundary (Pitfall #4 / A4).
- ContextBuilder.systemPrompt(for:): composes preamble FIRST, then
  presence enrichment, then memory hydration (D-12 — two distinct
  concatenation steps preserve cache_control breakpoints).
- TurnContext envelope with .empty static for the AppDelegate site
  (per-turn enrichment plumbing through orchestrator init is out of
  scope per D-12 fallback; AppDelegate calls .systemPrompt(for: .empty)).
- AppDelegate.swift orchestrator init now sources systemPrompt from
  ContextBuilder.

Rule 3 deviation (auto-fix blocking issue): the new
AgentCore.ContextBuilder name-collides with the pre-existing
JarvisVision.ContextBuilder (cloud-opt-in / frame-attach detector) at
two call sites that previously used bare `ContextBuilder()`. Both call
sites disambiguated to `JarvisVision.ContextBuilder()`:
- packages/AgentCore/Sources/AgentOrchestrator/AgentOrchestrator.swift:212
- App/AppDelegate.swift:1620
And the dependent test:
- packages/AgentCore/Tests/AgentOrchestratorTests/AgentOrchestratorVisionDispatchTests.swift:209

Wave-0 test preambleDoesNotEnableCacheUnintentionally flips RED→GREEN.
All 17 boundary gates green; check-app-builds.sh PASS.

Closes SELF-05, SELF-06 (Plan 10-02 implementation tasks).
This commit is contained in:
james.maes committed 2026-05-06 18:10:27 -05:00
1 parent 4249bc27ab
commit f22bf2ea3b
4 files changed
+116 -4

No files matched your search

+13 -2
View File
@@ -1262,7 +1262,15 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
toolDispatcher: mcpRuntime.dispatcher,
replayLog: replayLog,
sessionId: sessionId,
systemPrompt: "You are Jarvis, a personal macOS assistant.",
// Plan 10-02 (SELF-05 / SELF-06) — replaces the hardcoded
// "You are Jarvis, a personal macOS assistant." literal with
// ContextBuilder's locked self-aware preamble. The preamble
// names introspection tools so the model prefers calling them
// over generic "open System Settings" answers. Per D-12
// fallback the orchestrator still takes systemPrompt:String at
// init; per-turn presence enrichment continues to flow through
// PresenceStateSnapshot.shared (passed below).
systemPrompt: ContextBuilder.systemPrompt(for: .empty),
availableTools: [],
visionRouter: self.visionRouter,
presenceSnapshot: PresenceStateSnapshot.shared
@@ -1605,7 +1613,10 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
/// pending-frame slot so the camera capture is ready.
@MainActor
func tryPhraseAttachIfMatch(_ text: String) async {
let cb = ContextBuilder()
// Plan 10-02 disambiguation: qualify with `JarvisVision.` because
// AgentCore now also exposes a `ContextBuilder` (self-aware system-
// prompt composer). matchesFrameAttachPhrase lives on Vision's.
let cb = JarvisVision.ContextBuilder()
if cb.matchesFrameAttachPhrase(text), let fac = self.frameAttachController {
await fac.requestAttach(reason: .phraseDetected(in: text))
}
@@ -0,0 +1,93 @@
import Foundation
/// Composes the LLM system prompt for one turn.
///
/// Plan 10-02 (SELF-05 / SELF-06) introduces a locked self-aware preamble
/// that replaces the hardcoded `"You are Jarvis, a personal macOS
/// assistant."` literal previously sourced at `App/AppDelegate.swift:1242`.
///
/// **Invariants** (do not relax without re-spec):
/// - **D-12**: preamble is emitted FIRST, then per-turn enrichments
/// (presence, memory hydration). Two distinct concatenation steps —
/// preserves Anthropic `cache_control` boundaries (Pitfall #4).
/// - **D-13**: preamble is a single locked Swift string constant. No JSON
/// file, no localization, no runtime mutation.
/// - **D-14**: preamble does NOT enumerate the tool catalog as a Markdown
/// block. The Anthropic API tools array is the authoritative catalog;
/// the preamble nudges the model to call introspection tools by name so
/// it has handles, but does not duplicate schemas.
/// - **T-10-CACHE-01 / Pitfall #4 / Assumption A4**: preamble length stays
/// below the 4096-char Anthropic cache-eligibility boundary so it does
/// not unintentionally flip `cache_control` marker emission.
/// `CacheHintsEligibilityTests/preambleDoesNotEnableCacheUnintentionally`
/// is the regression guard.
public struct ContextBuilder: Sendable {
public init() {}
}
/// Per-turn context envelope that the system-prompt composer accepts.
///
/// Plan 10-02 introduces this as a minimal value type because the existing
/// `AgentOrchestrator` init takes `systemPrompt: String` directly — plumbing
/// a per-turn context through orchestrator init is out of scope per D-12
/// fallback. AppDelegate today calls `ContextBuilder.systemPrompt(for: .empty)`,
/// which yields the preamble alone; presence/memory enrichments continue to
/// flow through the orchestrator's existing per-turn paths
/// (`PresenceStateSnapshot.shared`, etc.).
public struct TurnContext: Sendable {
/// Optional presence enrichment text (vision/awareness fragment).
public let presenceText: String?
/// Optional memory hydration text (recalled facts for the turn).
public let memoryHydration: String?
public init(presenceText: String? = nil, memoryHydration: String? = nil) {
self.presenceText = presenceText
self.memoryHydration = memoryHydration
}
/// Empty context — preamble alone, no per-turn enrichment.
public static let empty = TurnContext()
}
extension ContextBuilder {
/// Locked self-aware preamble — D-13 single string constant.
///
/// Total length: well under 2 KB, deliberately below the 4096-char
/// cache-eligibility boundary so introducing the preamble does not flip
/// `cache_control` emission relative to the prior 10-token literal
/// (Pitfall #4 / T-10-CACHE-01).
///
/// Names the four self-knowledge MCP tools (registered in Plan 10-01)
/// plus the three starter tools so the model has handles to prefer
/// over generic "open System Settings" answers (D-14 — names only,
/// no schemas).
public static let selfAwarePreamble: String = """
You are Jarvis, an always-on macOS assistant running as a Swift app on \
the user's Mac. You have voice input via the user's microphone, voice \
output via the user's speakers, and a camera you can use to see when \
asked. You expose a set of MCP tools for introspection — always prefer \
calling those tools (list_audio_devices, get_active_audio_route, \
get_self_state, list_camera_devices, get_time, get_clipboard, \
run_applescript) over giving the user generic instructions like \
"open System Settings" or "I don't have access to your hardware." \
You are not a text-only assistant.
"""
/// Compose the full system prompt for one turn.
///
/// Order (D-12): preamble FIRST, then presence enrichment (if any),
/// then memory hydration (if any). Two distinct concatenation steps —
/// do not collapse into a single template; the boundary preserves
/// Anthropic prompt-cache breakpoints when callers later thread a
/// per-turn `TurnContext` through.
public static func systemPrompt(for turn: TurnContext) -> String {
var s = selfAwarePreamble
if let presence = turn.presenceText {
s += "\n\n" + presence
}
if let memory = turn.memoryHydration {
s += "\n\n" + memory
}
return s
}
}
@@ -209,7 +209,11 @@ public actor AgentOrchestrator {
var t2AvailableForThisTurn = false
if !input.images.isEmpty, let router = self.visionRouter,
let firstImage = input.images.first {
let cloudOptIn = ContextBuilder().matchesCloudOptIn(input.userText)
// Plan 10-02 disambiguation: qualify with `JarvisVision.` because
// AgentCore now also exposes a `ContextBuilder` (the self-aware
// system-prompt composer). The two types live in distinct modules;
// bare `ContextBuilder()` would be ambiguous to the type checker.
let cloudOptIn = JarvisVision.ContextBuilder().matchesCloudOptIn(input.userText)
let decision = await router.route(
for: firstImage,
prompt: input.userText,
@@ -206,7 +206,11 @@ final class AgentOrchestratorVisionDispatchTests: XCTestCase {
/// behaviour at the ContextBuilder boundary because the orchestrator
/// merely forwards the bool.
func testContextBuilderDetectsCloudOptIn() async throws {
let cb = ContextBuilder()
// Plan 10-02 disambiguation: qualify with `JarvisVision.` because
// AgentCore now also exposes a `ContextBuilder` (self-aware system-
// prompt composer). This test still targets the Vision module's
// cloud-opt-in detector.
let cb = JarvisVision.ContextBuilder()
XCTAssertTrue(cb.matchesCloudOptIn("send to opus, what's this"),
"ContextBuilder must flag 'send to opus' as cloud opt-in")
XCTAssertFalse(cb.matchesCloudOptIn("what's this"),