Product Objects & Platform Boundaries

The product layer separates conversation, execution, and delivery

Users operate conversations, tasks, teams, schedules, and deliverables—not an agent loop, tool registry, or context window. aibuddy models these concepts as separate objects so work remains inspectable after a page closes, a connection drops, or a sandbox is released.

aibuddy product objects organize around execution hosts Team and Schedule add collaboration and time-based triggering to Chat and Task. Projects, knowledge, and skills supply execution resources; completed results become Deliveries and Artifacts. Product objects organize around execution hosts Coordination, time, resources, and delivery attach to durable objects with clear responsibilities. Coordination and triggering Team Adds multi-agent collaboration to Chat Schedule Creates a new Task or continues an existing Task Execution resources Constrain environment and capability Project · Attachments Knowledge Skill Execution hosts Retain ownership, state, and traceable timelines Chat Continuing session Participants and messages Team process and results Task Goal and configuration State and steps Recovery and run records Both object types can host agent turns Durable delivery complete(paths) Delivery One user-visible delivery event Artifact · File storage Independent of message and sandbox lifetime Objects retain product state; services advance execution Boundaries locate ownership checks, recovery, and platform adaptation

Product objectWhat it retainsRelationship to execution
ChatContinuing conversation, participants, and message timelineHosts ordinary agent turns and can contain Team member process and delivery
TaskGoal, messages, state, steps, and run configurationHosts one traceable execution; a Schedule can create or continue a Task
TeamMembers, dependencies, and shared objectiveCoordinates persistent members inside a conversation and returns results to its timeline
ScheduleTime rule, target kind, model, and run recordsCreates a new Task or continues an owned parent Task when it fires
Project, Knowledge, SkillFile environment, formal source material, and reusable procedureConstrain the work environment and available capabilities before execution
Delivery, ArtifactOne delivery event and its durable filesTriggered by complete, separating results from messages and sandbox lifetime

These objects are not a flat feature list. Chat and Task are execution hosts; Team and Schedule add coordination and time-based triggering; Project, Knowledge, and Skill supply resources; Delivery records what reached the user. The boundaries attach ownership, state, and recovery to specific records.

Deliverables leave the task sandbox after complete

A file written in a sandbox is still an execution artifact. Only after the agent calls complete with its paths does DeliveryService read the bytes, store them in platform file storage, and persist a Delivery event with Artifact indexes. Preview and download read that file storage after another ownership check, so they do not require the original sandbox to remain alive.

Materialization maintains four boundaries:

  • It handles files, not directories presented as downloadable output.
  • The current per-file materialization limit is 25 MiB. An oversized or unreadable file does not create an empty index that later returns 404.
  • The same path under one execution host reuses a stable Artifact identity, updating current content instead of accumulating revisions indefinitely.
  • The Delivery event is written last and only when at least one file was materialized.

Agent delivery and durable platform storage are therefore adjacent but distinct steps. Per-file persistence is best effort and does not rewrite already-completed agent work as an execution failure.

Shared core is reused through ports, not shared infrastructure

Web and Desktop share the React product surface, data contracts, Hono route assembly, and domain services. Differences live at each composition root, where the host supplies repository, file storage, authentication, queue, realtime transport, scheduler, sandbox, and MCP implementations.

Shared semantics map through ports to Web and Desktop Both hosts reuse the product surface, createApp route assembly, and domain services. Web and Desktop diverge at identity, persistence, execution, and realtime infrastructure ports. Shared semantics map through ports to separate hosts Web and Desktop reuse product and domain layers while preserving real infrastructure boundaries. Shared product surface and client contracts @aibuddy/app · @aibuddy/common Shared HTTP route assembly @aibuddy/http · createApp · authentication/service ports Shared domain services and capability model @aibuddy/core · common · memory · knowledge · skill · tool Repositories, files, scheduling, sandboxing, realtime, and MCP are supplied through ports Web host adapters Hosted data and identity PostgreSQL · object storage Session · ownership · roles Distributed runtime Redis · BullMQ · worker Remote HTTP · SSE · WebSocket Desktop host adapters Local data and identity SQLite · local files Fixed local user · safeStorage Main-process runtime Task SSE · in-memory replay Chat WS · local projects · stdio MCP Shared interfaces align semantics; capability differences stay explicit at each composition root

The reuse goes beyond TypeScript types. The Desktop main process starts the same createApp used by Server over SQLite-backed services and a fixed local identity, then exposes it to the Renderer through loopback HTTP, SSE, and WebSocket. Web Server connects the same route tree to hosted identity, PostgreSQL, object storage, Redis, and workers. Route and service semantics can evolve together without pretending infrastructure failures are identical.

Web and Desktop fill the same ports differently

Platform concernWebDesktop
IdentityHosted session, resource ownership, and role checksFixed local-user; the owner of the local instance receives the admin role
Structured persistencePostgreSQLLocal SQLite
File persistenceR2/S3-compatible object storageLocal file storage under the application data directory
APIcreateApp on the remote ServerThe same createApp in the main process on loopback port 8003
Agent executionServer or worker execution using the current Node sandbox adapterMain-process execution that can enter a selected local project
Realtime pathTask over SSE and Chat over WebSocket; Redis can provide cross-process buffering and distributionTask over loopback SSE with replay and continuation from a main-process memory buffer; Chat over loopback WebSocket
MCPConnect to server-reachable MCP services with server-side credential injectionCan launch local MCP child processes over stdio
Knowledge summaryGenerated asynchronously when a summarizer is configuredNo summarizer is currently wired; authored during review

Desktop API keys are protected with Electron safeStorage before persistence; MCP environment variables remain part of the corresponding transport configuration. Web credential protection depends on server configuration and the deployment storage boundary. Both hosts still enforce ownership in the service layer; being local or inside a trusted network does not remove resource authorization.

Background execution shares a domain pipeline; hosts confirm completion

Schedule is a direct example of the port design. ScheduleService and createScheduleFireHandler own reloading current configuration, computing the next time, checking enabled state and quota, selecting a new or continuation Task, recording the fire, and decrementing runsRemaining after successful dispatch. The host supplies the scheduler and execution action.

A fully configured Web deployment uses Redis/BullMQ scheduling and worker execution. Its action returns a drainPromise, so the Schedule run moves from running to success or failed only after the task event stream drains. Desktop uses an interval scheduler in the main process and starts background work without requiring the Renderer to stay open.

The current Desktop Schedule adapter does not return the runInBackground completion promise to the shared fire pipeline. A dispatched run therefore does not immediately receive a terminal status; reconciliation marks an orphaned running record incomplete after process restart. This is a concrete host-completion parity gap, not capability already guaranteed by the shared Schedule model.

Platform consistency does not imply feature parity

The shared layer gives a Task, Delivery, or Knowledge state the same meaning on both hosts, but it does not erase host differences:

  • Without Redis, some Web queue, lock, and stream-buffer behavior degrades to process-local implementations.
  • Desktop Task-stream recovery covers Renderer disconnects while the main process remains alive. After reload, navigation, or dock closure, the client can replay buffered chunks and continue with live output; after the main process exits, recovery falls back to persisted messages. Ordinary Chat still does not accept the HITL-output and resume messages supported by the Web path.
  • Prompt-version and some preference-management routes are not yet injected into the Desktop loopback API.
  • Sandbox configuration includes Daytona and E2B variants, but the factory currently implements only the Node adapter.
  • Knowledge summarization and Schedule completion confirmation retain the platform differences described above.

These limits belong explicitly in the composition root and product capability map. Shared interfaces make differences locatable and replaceable; they do not justify describing the two platforms as identical.

Implementation anchors

ResponsibilityImplementation
Shared product UI and client contracts@aibuddy/app, @aibuddy/common
Shared HTTP route assemblycreateApp in @aibuddy/http
Agent, Task, Schedule, and Delivery semantics@aibuddy/core
Web repository and service compositionapps/server/src/service-registry.ts
Desktop service compositionregisterAllHandlers
Desktop loopback APIstartLocalApiServer
Desktop Task-stream recoverycreateDesktopTaskStreamer, createInMemoryStreamBuffer
Deliverable materializationDeliveryService
Platform-neutral schedule firingScheduleService, createScheduleFireHandler
Was this page helpful?
Edit on GitHub