6.10 Architecture and package boundaries

This page is for developers changing Teloa source. Locate the relevant package, then follow the user action, business state and execution result through the full path.

Responsibilities along one work item

User input -> React workspace -> Harness / RPC -> Business services -> PostgreSQL
                                  |
                                  -> Native sessions, models and tools
                                  |
Execution events -> Task / Run state and results -> Original conversation and task UI

Teloa preserves business ownership of employees, work, approvals and results; DSH supplies native execution. A model response, execution ending and business acceptance are separate facts.

Where to make a change

Directory	Responsibility	Typical changes
packages/contract	Types, format readers and validation	Fields, templates, requests and responses
packages/backend	Persistence, transactions, idempotency and rules	Task state, fixed results and grants
packages/harness-dsh	Engine adaptation and tool authorization	Context, dispatch, stop and result return
packages/client/ui-workbench	Workspace UI and state presentation	Employees, groups, tasks, settings and drawers
packages/client/ui-kit	Shared UI components	Controls and common interaction containers
packages/bundle	Fixed plugin compositions and presets	Runtime composition and preset configuration
packages/sdk	External employee contract and client	Shared HTTP, SDK and MCP formats
packages/cli	Native installation and service lifecycle	Startup, stop, backup and upgrade
packages/mcp-reference	Read-only reference MCP service	Listing, versioned reads and denials
packages/local-embedding	Local retrieval adapter	Preparation, embeddings, indexes and search

The AI Team, Agent Studio and Agent Harness product layers explain product responsibilities; they do not map one-to-one to packages.

Follow an employee call

Read these files in order for the external employee API:

1. packages/sdk/contract.mjs: request fields, states and results.
2. packages/harness-dsh/src/employee-integration-host.ts: HTTP/MCP authentication and dispatch.
3. packages/backend/src/work/employee-integrations.ts: fixed employee version, scope and permissions.
4. packages/backend/src/work/employee-api-work.ts: work, rounds, idempotency, results and events.
5. packages/harness-dsh/src/task-runs.ts: native preparation, start, reconciliation and stop.
6. packages/client/ui-workbench/src/client/EmployeeIntegrationSettings.tsx: owner integration management.

Run the employee integration example to observe the behavior. Follow the same work, Task and Run IDs; do not combine another work item's result with the task you are investigating.

Change a cross-package field

For a new task field, update its contract and defaults, persistence, adapter parsing and client presentation. Add migration and compatibility reads where needed, then cover old data, new data and invalid values.

Changing a TypeScript type is insufficient: runtime readers may reject unknown fields. The UI must not bypass business services with direct database access.

Extension points

• New working method: start with a SKILL, usually without core changes.
• New external system: start with an MCP app, enforcing service-side access and employee grants separately.
• New resource type: update readers, preview, import, sharing and tests, preserving subject restrictions.
• New execution component: preserve identity, grants, cancellation and provenance through engine boundaries.
• Local models: existing voice and retrieval setup is in the settings guide; new providers need separate preparation, runtime and authorization verification.

Prepare an isolated local environment, then validate through testing and contributing.