Skip to content

Personal AI, On Personal Devices

Python
11.7 KB
Raw Blame

Cross-device travel planning handoff

A standalone Rust template for a laptop coordinating work with a phone for “Make travel plans for me.” It demonstrates device ownership, task messages, routing, and failure behavior before building real infrastructure.

Everything is deterministic and synthetic. Both devices run in one process; requests and responses cross an in-memory JSON serialization boundary. There is no network connection, mobile integration, real model inference, live travel research, calendar write, or booking. Saving a draft only changes synthetic in-memory state.

Run it

Requires Rust 1.88 or later. Run these commands from the repository root:

cargo run --manifest-path examples/cross_device_travel/Cargo.toml -- happy
cargo test --manifest-path examples/cross_device_travel/Cargo.toml

CI also runs this crate's formatting, Clippy, and tests independently.

The executable prints JSON. report.events contains the full task request and response messages; final_output contains the assembled result. The checked-in happy-path trace is generated by the same executable:

cargo run --quiet --manifest-path examples/cross_device_travel/Cargo.toml -- happy > examples/cross_device_travel/traces/happy.json

Pass one scenario name after -- (default: happy; --help lists options). An aborted workflow still prints its report and exits with status 1.

Scenario Demonstrates
happy Phone context, laptop research and planning, then a phone draft.
phone-offline Optional phone work is unavailable; laptop planning proceeds with explicit gaps.
photos-denied Photo access fails; other context still contributes to the plan.
research-retry A transient research failure is retried within a fixed limit.
save-timeout A phone draft times out; the action is not retried automatically.
laptop-offline Required laptop work cannot run; the workflow aborts.

This crate builds independently of the main Rust workspace.

Walkthrough

The laptop creates a fixed, topologically ordered task list for this exact request and synthetic trip assumptions. A future general natural-language planner can produce the same task structures. The happy path plans three days in Montreal from Boston, using phone-provided dates and interests.

The happy trace executes these six steps sequentially, one successful attempt each:

Task / executor Input and dependency outputs Synthetic output
mobile_context / phone Fixed travel request. Origin: Boston; timezone: America/New_York.
photo_interests / phone Fixed travel request. Interest summary: architecture and parks.
calendar / phone Fixed travel request. Available dates: October 16–18, 2026.
research / laptop Destination: Montreal; mobile_context + photo_interests. Air/rail candidates and a central-area stay, all synthetic and unverified.
plan / laptop Model profile: large_local; mobile_context + calendar + research. Oct 16 arrival, Oct 17 architecture, Oct 18 parks/return; selects the air/stay fixtures; execution backend: mock.
save_draft / phone Completed plan. Draft travel-demo-001:save_draft in demo memory; no bookings.

Dependency flow: mobile_context + photo_interests → research; mobile_context + calendar + research → plan; plan → save_draft. Research and planning are required; their failure aborts the remaining workflow. Phone tasks are optional; failures produce explicit gaps or an unsuccessful draft. The assembled final_output has status: "completed", the plan, no warnings, and draft_status: "saved_in_demo_memory" on this happy path.

The phone returns summaries and availability rather than its raw photo library. The laptop owns research and larger planning steps. Routing requires the requested capability, device kind, and online status, with a stable device-ID tie break. An unavailable phone capability does not silently migrate to the laptop. Discovery assumes one user's single paired phone; it does not authenticate device ownership.

Only successful outputs from explicitly declared dependencies enter a task's context. Failed optional dependencies are omitted; their failures remain visible in the trace. The final report preserves missing inputs and unsuccessful actions so a partial plan cannot be mistaken for a confirmed booking or calendar update. Missing calendar context produces unconfirmed dates. Supplied available_dates must contain exactly three nonempty strings; invalid payload shapes are rejected.

Code and interfaces

File Responsibility and replacement point
src/protocol.rs Serde request/response types and independent protocol version 1.
src/runtime.rs DeviceTransport, discovery, routing, dependency context, retries, and failure handling.
src/travel.rs Laptop decomposition, phone fixtures, mock device dispatch, and final output assembly.
src/laptop.rs research_travel option records and the LaptopPlanner inference boundary; validates scheduling context and consumes research options.
src/main.rs Scenario selection and JSON report output.

The same workflow can be invoked from Rust:

use openjarvis_cross_device_travel::runtime::Orchestrator;
use openjarvis_cross_device_travel::travel::{decompose, DemoTransport, Scenario};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tasks = decompose("Make travel plans for me.")?;
    let transport = DemoTransport::new(Scenario::Happy);
    let report = Orchestrator::new("laptop", transport).run("travel-demo-001", &tasks)?;
    assert!(!report.aborted);
    Ok(())
}

The laptop handlers expose concrete research and heavier-model replacement points:

use std::collections::BTreeMap;
use serde_json::Value;
use openjarvis_cross_device_travel::protocol::TaskError;
use openjarvis_cross_device_travel::laptop::{
    research_travel, LaptopPlanner, MockLaptopPlanner, PlannerRequest,
};

fn run_laptop_steps(
    research_context: &BTreeMap<String, Value>,
    planning_context: &mut BTreeMap<String, Value>,
) -> Result<Value, TaskError> {
    let findings = research_travel("Montreal", research_context)?;
    planning_context.insert("research".into(), findings);
    MockLaptopPlanner.plan(PlannerRequest {
        model_profile: "large_local", context: planning_context,
    })
}

Here research context contains successful mobile_context and photo_interests outputs; planning context starts with successful mobile_context and calendar outputs. large_local describes intended laptop placement; MockLaptopPlanner returns deterministic fixtures without loading a model. Replace its LaptopPlanner implementation with local inference, retaining the request/result boundary.

DeviceTransport::discover supplies device advertisements to the laptop. The runtime selects a device by capability and device kind, then calls DeviceTransport::execute with an addressed task request. The mock adapter decodes that request, calls the corresponding phone or laptop fixture handler, and returns a typed response. Replace the transport to cross a real process or device boundary; replace fixture handlers to call mobile APIs or laptop tools.

The protocol is a demo contract, not an implementation of the A2A specification. The trace is an executable example of the following envelopes:

Request field Meaning
version Demo protocol version.
workflow_id, task_id Correlate the workflow and stable logical task.
attempt Distinguish attempts of that same task.
from_device, to_device Identify sender and selected executor.
capability Name the requested device function.
input Task-specific arguments.
context Successful outputs from declared dependencies.
timeout_ms Execution timeout budget for the transport to enforce.

Responses carry version, workflow_id, task_id, attempt, and device_id, plus an outcome tagged with status: "succeeded" or status: "failed". The runtime validates every response correlation field before accepting an output. It also rejects empty or duplicate task IDs and invalid dependency order before dispatch.

Read capabilities get at most two attempts, and actions get one. Retries require a retryable timeout, unavailable-device error, or execution failure. Routing failures do not dispatch or retry; rediscovery requires another workflow run. A write timeout can mean the action happened but its reply was lost; save_draft is therefore never automatically retried. Any failed dispatched draft is conservatively reported as uncertain, including a disconnect or invalid reply; not_saved is reserved for routing failures that prevented dispatch. Stable task IDs support future idempotency work but do not provide durable deduplication or exactly-once delivery.

Timeout enforcement belongs to the transport. The mock explicitly simulates timeouts; it does not start a real timer or interrupt running work.

OpenJarvis integration map

These future integration points are outside the demo's runtime and dependencies.

Existing interface Proposed adapter
rust/crates/openjarvis-agents/src/traits.rs: OjAgent::run Wrap the laptop workflow as an agent; map AgentContext and AgentResult metadata to workflow context and results.
rust/crates/openjarvis-tools/src/traits.rs: BaseTool Expose device dispatch with a ToolSpec argument schema and a ToolResult response.
src/openjarvis/a2a/client.py: A2AClient Adapt discovery to agent cards and dispatch to the existing tasks/send endpoint.
src/openjarvis/a2a/tool.py: A2AAgentTool Follow the existing remote-agent-as-tool pattern for Python orchestration.
rust/crates/openjarvis-core/src/hardware.rs: detect_hardware Populate laptop compute advertisements; peer discovery still needs its own adapter.
rust/crates/openjarvis-core/src/types.rs: Trace, TraceStep Record routing, tool calls, and responses in OpenJarvis tracing.

Integration needs explicit adaptation. Rust A2A currently uses pending/active/cancelled, whereas Python uses submitted/working/canceled; their agent-card and task fields also differ. Do not forward these demo messages directly into either implementation and assume compatibility. A production adapter should check JSON-RPC errors and task completion explicitly.

The Rust OrchestratorAgent currently performs a single model chat and leaves multi-turn tool dispatch for future work. Its ToolExecutor registers a closed BuiltinTool enum, so adding an arbitrary remote BaseTool also requires an integration change. Those changes are outside this example's scope.

Productionization decisions

  • Replace static advertisements with authenticated discovery, capability versions, permission state, and reachability/expiry handling. Bind private data to its specific owning device and user, beyond the demo's device-kind constraint.
  • Add an actual transport with enforced deadlines, device identity, reconnect behavior, and payload limits; retain the runtime's response correlation checks.
  • Add persistent task state, action idempotency, timeout reconciliation, and cancellation semantics before retrying actions across device disconnects.
  • Replace fixtures with phone permission-aware data adapters, real research tools, and a laptop planner that asks for missing trip constraints.
  • Define consent and data-minimization rules for real phone context; keep raw private data on its owning device where possible.
  • Extend static dependency validation to generated plans, and add concurrent scheduling and durable trace storage when the execution model needs them.