Skip to main content

Quick Reference: Local/Remote Task Execution & Credits

ARCHIVE — This document is historical reference only. It may contain outdated information. See docs/status.md for current project state.

Status: ✅ Feature planned and approved (2026-02-15) Timeline: ~6-8 weeks (13 implementation steps) Complexity: Large (L)

What Users Will See​

1. Execution Preference​

When creating a task, users/AI can specify:

  • "local" → Force run on device (Tauri)
  • "remote" → Force run in cloud (Python backend)
  • "auto" → Let router decide (default)
  • "cost_optimized" → Pick cheapest option
  • "performance_optimized" → Pick fastest option

2. Cost Estimation​

Before executing, see:

"This will cost 5 credits and run in the cloud"
"This will cost 0 credits and run locally"
"Estimated time: 2 seconds"

3. Quota Display​

In settings:

Weekly Credits: ████████░ 240/250 remaining
Monthly Credits: ██████░░░░ 750/1000 remaining

4. Execution Badge​

On task cards:

⚙️ Running locally       (green)
☁️ Running in cloud      (blue)
⏳ Queued               (gray)
🚫 Blocked (over quota) (red)

5. Quota Warnings​

  • Weekly soft limit (80%): Warning banner, task still executes
  • Monthly hard limit (100%): Task blocked, can request override

What the Backend Does​

Task Router​

  1. Evaluates: capability + user preference + quota
  2. Decides execution location
  3. Returns estimated cost + executor ID

Credits Service​

  1. Calculates credits (base × multiplier × token factor for LLM)
  2. Charges upfront when task starts
  3. Refunds overage if actual cost < estimated
  4. Tracks in task_credits table for audit

Task Processor​

  1. Routes task (get decision from TaskRouter)
  2. Checks quota (blocks if hard limit exceeded)
  3. Charges credits
  4. Executes task
  5. Updates actual cost

Credit Costs (Configurable)​

Defined in config file per integration:

gmail:
  send: 1.0 credit
  read: 0.5 credit
  draft: 0.3 credit

llm:
  chat: 0.01 per 1000 tokens
  embed: 0.005 per 1000 tokens
  complete: 0.01 per 1000 tokens

local_embedding: 0 credits (always free)

google_calendar:
  list_events: 0.1 credit
  create_event: 0.2 credit

slack:
  send_message: 0.5 credit
  read_messages: 0.3 credit

Execution surcharge:

  • Local: 0% (no surcharge, free if applicable)
  • Remote: 1x base cost
  • Remote peak hours: 1.2x base cost (future)

Quota System​

Two-Tier Model​

  • Hard Monthly Limit (e.g., 1000 credits/month)

    • If exceeded → task blocked until reset
    • Reset on billing date (configurable)

  • Soft Weekly Limit (e.g., 250 credits/week)

    • If approached (80%+) → warning banner
    • Task still executes, user can confirm
    • Reset every Sunday (configurable)

Per-Space Quotas​

  • Each space has independent quota
  • Sub-spaces inherit parent quota by default
  • Can override per sub-space

Admin Override​

  • Admins can temporarily override quota for urgent tasks
  • Logged for audit trail

Storage Abstraction​

Implemented:

  • TaskStore ABC (abstract base class)
  • PostgresTaskStore (MVP, existing database)

Future (Phase 4):

  • RedisTaskStore (distributed queue, multiple workers)
  • S3TaskStore (archive long-term task history)

Benefit: No code changes needed to swap backends.

Key Design Decisions (Approved)​

DecisionValueRationale
RoutingUser-specified + smart defaultsFlexibility for different use cases
Credit CostBackend-driven, per-action + token multiplierAudit trail, configurable per instance
Quota EnforcementMonthly hard + weekly softSafety valve + pacing help
StorageAbstraction (ABC) + PostgreSQL MVPFuture-proof for scaling

Database Changes​

New Columns (tasks table)​

  • execution_preference (enum: local/remote/auto/cost_optimized/performance_optimized)
  • execution_location (enum: local/remote/hybrid)
  • executor_id (string: "tauri:device-id" or "python:worker-1")
  • estimated_credits (numeric)
  • actual_credits (numeric)
  • execution_metadata (JSONB)

New Tables​

  • task_credits — audit trail (task_id, space_id, interface_id, credits, reason)
  • space_quotas — quota limits (space_id, monthly_limit, monthly_used, weekly_limit, weekly_used)

Indexes​

  • task_credits: task_id, space_id, interface_id, created_at
  • space_quotas: space_id

API Changes​

New Endpoint​

POST /api/tasks/estimate

Request:

{
  "type": "message",
  "description": "Summarize this email",
  "space_id": "...",
  "group_id": "...",
  "execution_preference": "cost_optimized",
  "input": { "email_id": "..." }
}

Response:

{
  "execution_location": "local",
  "estimated_credits": 0,
  "estimated_duration_ms": 2000,
  "executor_id": "tauri:macbook-pro-seb",
  "rationale": "local handler available + cost_optimized preference",
  "quota_status": "OK",
  "quota_message": "120 credits remaining this week"
}

Testing Strategy​

  • Unit tests: Router logic, credit calculations, quota checks
  • Integration tests: End-to-end task → routing → execution → charge
  • E2E tests: User creates task → sees estimate → confirms → watches badge update
  • Performance tests: Router <100ms, credit calc <50ms

Implementation Steps​

Phase 1: Backend Foundation (Days 1-10)

  1. Database migrations
  2. Pydantic models + enums
  3. TaskStore ABC + PostgreSQL implementation
  4. TaskRouter service
  5. TaskCreditsService

Phase 2: Integration (Days 11-20) 6. Refactor TaskService to use TaskStore 7. Update TaskProcessor with router + credits 8. Integrate into startup 9. API estimate endpoint 10. Migration script

Phase 3: Frontend (Days 21-25) 11. Task card location badges 12. Quota display + settings UI

Phase 4: Testing + Polish (Days 26-30) 13. Integration + E2E tests 14. Documentation 15. Performance tuning

Success Criteria​

  • ✅ Tasks track execution location (local/remote)
  • ✅ Credits calculated per-action + token multiplier for LLM
  • ✅ Quotas enforced (hard monthly, soft weekly)
  • ✅ User can choose execution preference
  • ✅ Frontend shows location + credits + quota status
  • ✅ Storage abstraction ready for future backends
  • ✅ >80% test coverage
  • ✅ All docs updated
  • Design: docs/features/2026-02-15-local-remote-task-execution.md
  • Implementation: docs/features/2026-02-15-IMPLEMENTATION_PLAN.md (13 detailed steps)
  • Architecture: Will update docs/architecture.md during implementation

Contact / Questions​

Any questions about design or implementation? Refer to the full docs above or ask during implementation.

Feature approved by user on 2026-02-15. Ready to start implementation.