[P1][Desktop Agent] Build a paired edge agent for private repositories, local files/models, device capabilities, and signed edge jobs

[Ankit6149]

Parent epics

#55, #64, #170

Product outcome

SignalFlow has a lightweight paired desktop component for capabilities that cannot or should not live purely in the browser/cloud:

• private/local repositories;
• explicitly authorized local files/folders;
• local model runtimes;
• Private Hybrid preprocessing;
• optional officially supported local AI-agent adapters;
• future desktop app capture/automation;
• secure cloud-to-device jobs.

The Desktop Agent is a tray/menu-bar capability service, not a second full SignalFlow UI.

Canonical components

Desktop Agent
├─ pairing/session manager
├─ device capability service
├─ authorized file/repository bridge
├─ local inference adapter
├─ private-hybrid preprocessing worker
├─ secure edge job receiver
├─ resumable upload/download manager
├─ optional local-agent adapters
├─ future capture/automation adapters
└─ diagnostics/user controls

PairedDevice contract

Suggested fields:

deviceId
workspaceId
userId
deviceName
platform
agentVersion
deviceCredentialRef/public key
capabilities[]
processingPolicySupport[]
lastSeenAt
trustState
revokedAt?

Local root authorization

Users explicitly grant roots/repositories. No whole-disk access by default.

Requirements:

• normalized canonical paths;
• symlink/path traversal protection;
• per-root revoke;
• project/workspace scope;
• no stale recipe/job access after permission removal;
• private file contents excluded from diagnostics/logs.

Edge job model

Suggested fields:

edgeJobId
workspaceId
deviceId
kind
resourceReferences[]
processingPolicyId
capabilityRequirements[]
expiresAt
idempotencyKey
status
attempt

States:

queued
waiting_for_device
delivered
accepted
running
uploading
succeeded
failed
rejected
expired
cancelled

Security

• explicit device pairing;
• revocable device identity;
• signed/short-lived job claims;
• replay protection;
• idempotency;
• workspace authorization;
• no raw provider/device secrets in jobs;
• secure artifact transfer;
• fail closed when capability/policy mismatch occurs.

Private Hybrid proof

confidential repo evidence request
→ paired device
→ authorized root
→ local extraction/summarization/privacy scan
→ minimal structured evidence
→ cloud reasoning only if policy allows

Local AI / local agent boundary

• local SLM runtime integrates with [P1][Local AI] Build curated local intelligence registry, device capability assessment, and downloadable private-processing packs #173/[P0][Inference] Add task-oriented provider capability registry, policy-aware routing, metering, and fallback #171;
• optional Codex/Claude Code/etc. adapters only through officially supported programmatic modes;
• local CLI does not automatically mean local data processing;
• capability declares whether provider cloud receives content;
• no unsupported credential extraction.

Acceptance criteria

• Device can pair/revoke safely.
• Capabilities are reported truthfully and versioned.
• User can authorize/revoke one local repository root.
• Signed edge job survives disconnect/reconnect according to policy.
• Duplicate/replayed job cannot duplicate canonical results.
• Private Hybrid fixture produces structured evidence without uploading raw repo bytes to cloud storage.
• Local inference capability integrates with provider-neutral routing.
• Diagnostics contain no raw source/secrets.
• Offline device appears as waiting/unavailable rather than silently rerouting protected work.

Non-goals

• no full desktop Studio UI;
• no arbitrary whole-disk access;
• no hidden recording;
• no unsupported consumer-session reuse;
• no desktop-app capture required in this issue.

Definition of done

Close only when a paired desktop can safely execute one real private-processing job against an explicitly authorized local repository and return a canonical result while cloud/web/mobile observe the same durable job state.