---
title: Source architecture and package boundaries
description: Understand how shared contracts connect business services and the Harness adapter.
lastVerified: 2026-10-02
---

# 6.7 Source architecture and package boundaries

The client expresses user actions, the backend maintains business state, and the Harness adapter runs models and tools. Shared contracts connect these layers.

```text
React work interface
      │ Shared contracts
Harness / RPC adapter ── DSH models, sessions, and tools
      │
Business services ── PostgreSQL
      │
Resources, tasks, employees, groups, and automations
```

The product architecture is **AI Team / Agent Studio / Agent Harness**: team delivery, work configuration, and the runtime foundation. The diagram and package table describe implementation and do not map one-to-one to those product layers. Keep business, data, and execution planes in the system view. See [Business capabilities and execution engines](https://docs.teloa.ai/v/0.2.3/markdown/en/develop/engine-integration.md) for native object mappings.

## Where the code lives

| Package | Responsibility |
| --- | --- |
| `packages/contract` | Shared types, data formats, and validation |
| `packages/backend` | Persistence, business rules, transactions, and idempotency |
| `packages/harness-dsh` | DSH integration, RPC, execution, and authorization checks |
| `packages/client/ui-workbench` | React product interface and interaction state |
| `packages/client/ui-kit` | Shared UI functionality |
| `packages/bundle` | Plugin composition and presets |
| `packages/mcp-reference` | Minimal read-only reference service |
| `packages/local-embedding` | Development pilot: optional local embedding extension, locked-version model file preparation, and inference worker |

## Role collaboration and native execution

The product distinguishes two layers. AI employees are lasting role identities with skills, role memories, and permissions; work groups support business collaboration with the user. Task teams divide the current task, and task assistants are their temporary members. Either an ordinary conversation's lead agent or an AI employee can start a task team without a work group.

**DSH Agent Team** implements task teams. Teloa reuses the official roster, mailbox, task dependencies, messages, and execution services. Thin adapters retain business ownership, authorization, and delivery projections rather than introducing another agent engine or parallel DAG. Task/Run owns business attribution and acceptance; official Team and jobs own execution facts.

A temporary teammate in a managed Run uses that run's fixed authorization and quota. It does not automatically acquire a lasting role, and a member name cannot grant another employee's identity or permissions. Stopping first blocks new delegation, then cancels linked members and background work. Business execution closes only after they actually finish; member completion alone is not business delivery.

Sustained delegation uses official `spawn_teammate`; managed one-off delegation retains `subagent_task`. Older child sessions keep official reading and control services without becoming fabricated Team members. Product interfaces and user guides use “task team” and “task assistant”; implementation names belong in developer documentation.

Role conversations use the public asynchronous `system-prompt/assemble` interface in DSH `0.1.7-rc.1`. The official runtime-context projection carries the current role definition instead of automatically sending a long role description as the user's first message. Each request checks the owner's conversation binding, creation identity, active role link, and current definition. The official projection produces a new snapshot when the identity or version changes, while the original user message remains unchanged. A manual introduction sends only a short request. Task/Run keeps its existing fixed task context, and native child agents skip this ordinary role-conversation adapter. Existing tool and material authorization checks remain in place. Read failures, retirement, and mismatches between the fixed creation identity and role link reject the request rather than silently treating it as an ordinary conversation.

## Delivering local specialist models

A developer-provided local model should deliver a recognizable capability, such as speech transcription, document recognition, or assisted alert classification. DSH's existing local speech provider owns weight preparation, status, and inference. Teloa reuses it while building marketplace discovery, solution dependencies, and business integration. Each additional non-speech provider needs its own validation; a working local chat model does not establish a complete specialist-model ecosystem.

The local speech resource is `teloa.model.sensevoice`: Marketplace > Models > Prepare local speech > the native plugin list inside Teloa settings > Voice Input. Initial activation requires a restart, followed by explicit confirmation to download and prepare the model. The catalog stores `delivery: reference`, `model.form: local-specialist`, the `speech-to-text` usage, and a fixed native provider reference. It does not store weights, installation commands, or a second download state. The native plugin manager is the sole owner of `plugins.bundle.config`; the marketplace must not declare another owner. The native page currently has no public deep link to a plugin detail, so the user selects Voice Input after opening the list.

SenseVoice uses the reviewed `dsh-speech / sensevoice-local` binding. Its online-index compatibility range starts at `0.2.0-alpha.7` to protect older readers that cannot parse this form. Local retrieval uses fixed adapters for Qwen3 Embedding 0.6B and EmbeddingGemma 2, maintained separately from the marketplace model catalog. Weight and source-code licenses are separate. Search and conversation guidance do not enable plugins, download weights, or change the chat model. Third-party OCR, classification, and ranking adapters are not implemented; changing a provider name in the catalog does not make them installable.

Plugin code, model weights, and host runtime bindings are managed separately. Reuse native preparation services where available; large weights do not belong in the Skill text-content store. Specialist models bind to their capability or tool, while only conversational models enter the chat model picker. The lead assistant may continue using a cloud model. Local means the Teloa host, such as a user's Mac mini, which may differ from the device opening the web page. Hardware compatibility, memory use, and quality require measurements for each model. General third-party model publishing and runtime adapters are still under development.

Users deploy and maintain private medium and large models on their own GPU servers. Teloa connects through DSH's native Custom Model API; it does not deploy or schedule GPUs or download these weights to the client. A remote fallback may be a private model service. Remote does not mean public cloud: primary and fallback models follow the user's configuration. Connecting to a private model service does not confine the entire task to an intranet; tool and subtask egress needs separate verification.

### Local Chinese retrieval

::: info Capability and catalog status
This release includes retrieval adapters for Qwen3 Embedding 0.6B and EmbeddingGemma 2. Review their sources, capacity and licenses in the Knowledge retrieval-model panel, then explicitly prepare and select a model. These adapters are maintained separately from the official marketplace model catalog; arbitrary marketplace models are not installable through these fixed adapters.
:::

`@teloa/local-embedding` uses Qwen3-Embedding-0.6B to locate passages in authorized materials and provides 1024-dimensional embeddings. It is an optional Teloa extension, not DSH's native speech service, and does not enter the conversation, employee, or default chat model picker. The lead assistant keeps its own chat model. Local refers to the host running Teloa.

```text
Owner explicitly enrolls materials -> ResourceService read -> Chunking -> Local embedding -> PostgreSQL index
Native retrieval tool -> Conversation/role authorization -> Query embedding -> Rank authorized candidates
                      -> ResourceService transactional read -> Excerpts with sources, versions, and original ranges
```

Index construction and embedding computation run locally on the Teloa host. Excerpts returned by the retrieval tool enter the current chat model's context. When the conversation uses a remote model, those excerpts may be sent to that model service, including a privately deployed remote service. Local retrieval therefore does not guarantee that the entire question-and-answer flow stays on the host or works offline.

After checking DSH **0.1.7-rc.1**, the pilot reuses Cordis optional service discovery and lifecycle, `ctx.subprocess` process management, `dshHomePath()` host directories, `withFileLock` preparation exclusion, and `ctx.tools.register(defineTool(...))` with native ToolRuntime. That version exposes neither general embedding inference nor a generic model file preparation interface, and SenseVoice's preparer is not exported for non-speech reuse. The additional implementation is therefore limited to locked-version model file verification, the ONNX worker, and the `teloaEmbedding` state service. Speech continues to use the official implementation.

#### Preparation and model file provenance

The extension is outside the default bundle, and enable/disable settings take effect after restart. Enabling only checks the cache; it does not download, install, or load the model. The user reviews sources, capacity, and licensing in the preparation interface and confirms before runtime and model file preparation begin, in that order. **`onnxruntime-node@1.30.0`** is not shipped with the application. It uses Teloa's existing managed installer, bundled lock, `npm ci --ignore-scripts`, and integrity checks. `embed()` accepts only `ready/standby`, starts a worker on demand from standby, and rejects unprepared models without implicitly installing them for a query.

The model uses a locked revision of `onnx-community/Qwen3-Embedding-0.6B-ONNX`: **a community conversion, not the original vendor's files**. The upstream model is `Qwen/Qwen3-Embedding-0.6B`, and tokenizer files come from a locked upstream revision. The fp32 ONNX graph and external weights total approximately **2.40 GB**, with tokenizer files and the managed runtime required separately. `runtime/assets.json` pins URLs, byte counts, SHA-256 hashes, variants, and configuration; `runtime/onnxruntime.json` holds the runtime recipe. The extension's `PROVENANCE.md` and `LICENSE-MODEL` record provenance and the basis for the upstream Apache-2.0 license. Teloa does not convert, host, or mirror weights. Preparation accepts only pinned npm/Hugging Face sources and allowed CDN redirect hosts; the preparation screen can instead use the `hf-mirror.com` mirror, which changes only the host while the path and pinned revision stay the same, every file is still checked against its pinned byte count and SHA-256, and the choice applies to that preparation only and is not saved. Inference does not automatically fall back to a remote embedding service.

#### Authorization, indexes, and shared dependencies

The owner explicitly enrolls individual materials; agents cannot enroll sources or expand scope themselves. Once the model is ready, the owner's ordinary conversations can call `teloa_knowledge_search` by default within their actual bound scope. Managed tasks additionally require role tool permission and task material authorization. The tool accepts only a query and result limit, not model-selected file paths, owner identities, or authorization scopes. Results distinguish searched materials from those awaiting indexing. Excerpts are bounded to 2 KiB each and 16 KiB total, within ResourceService's read boundaries.

Indexes share PostgreSQL with material metadata. They store vectors, original ranges, and hashes without duplicating chunk text. Each vector contains 1024 float32 values, totaling 4096 bytes. An index binds its owner, resource/content versions, scope, model `profileHash`, and chunker version. Every query rechecks these bindings, then reads source text through ResourceService in a transaction. The in-memory vector cache does not cache authorization. Withdrawn, removed, or mismatched versions cannot produce hits. Enrollment follows a source through revisions, while new versions require indexing. Startup and service availability trigger reconciliation; disabling the extension does not delete weights or the managed runtime.

A v3 solution can declare `teloa.model.qwen3-embedding-0-6b@1.0.0` with `usage: embedding` on the resource that needs it. The declaration grants neither the retrieval tool nor material access. Two solutions can share one provider, and uninstalling one does not remove their shared model. Disabling the extension blocks creation and repeated execution of dependent resources while leaving independent resources and historical task reads available. Unsupported catalog resources or versions retain their declarations and show their status; test resources cannot bypass the production catalog reader.

#### Model and hardware limits

The default is **fp32 with the official query instruction**; int8 is for evaluation only. Similarity does not establish that the materials contain an answer. **M1/M2 Mac mini 8 GB has not been verified on hardware.** File size alone does not establish memory use or speed. Check quality and capacity on target devices and business materials; unit tests and simulated catalogs are not evidence of production resource integration.

Developers submitting a similar provider need usage and input/output contracts, locked-version model files and provenance, a runtime recipe and lock, licensing, and evidence for state transitions, refusal before readiness, download integrity, cancellation, idle release, quality, and hardware. The existing extension package provides an interface reference. Catalog bindings still use a reviewed allowlist; entering an arbitrary provider name cannot install third-party code.

### Declaring model dependencies in a solution

::: info Protocol scope
Business packages support model dependency declarations in `teloa.business-package/v3`. Declarations do not install models or grant tools. Execution depends on reviewed catalog bindings, actual provider state and current business permissions.
:::

A v3 `skill` or `work-template` resource can declare `modelDependencies` on the resource that uses the model. The v2 format retains its existing structure and rejects this new field. Each item permits only `catalogId`, a fixed catalog `version`, `usage`, and `required`. When present, the field must contain 1–16 items, with no duplicate model-and-usage pairs. The manifest accepts no download URLs, commands, credentials, or runtime addresses.

The following two files form a minimal solution. This example demonstrates a prerequisite: the user creates and checks text through native voice input, then the task organizes that text. **Declaring a dependency does not grant an audio transcription tool or select SenseVoice as the chat model.** A task that processes audio files directly still requires an actual tool integration and its authorization.

`teloa.json`:

```json
{
  "format": "teloa.business-package/v3",
  "id": "voice-notes",
  "title": "Voice work notes",
  "version": "1.0.0",
  "domain": "general",
  "scope": "general",
  "description": "Organize text provided through native voice input.",
  "resources": [
    {
      "id": "summarize-notes",
      "kind": "work-template",
      "title": "Organize voice notes",
      "version": "1.0.0",
      "required": true,
      "source": {"kind": "local", "path": "tasks/voice-notes.json"},
      "modelDependencies": [
        {
          "catalogId": "teloa.model.sensevoice",
          "version": "1.0.0",
          "usage": "speech-to-text",
          "required": true
        }
      ]
    }
  ],
  "relations": [],
  "entrypoints": ["summarize-notes"]
}
```

`tasks/voice-notes.json`:

```json
{
  "format": "teloa.work-template/v1",
  "id": "summarize-notes",
  "title": "Organize voice notes",
  "version": "1.0.0",
  "domain": "general",
  "description": "Organize supplied transcript text without reading or transcribing audio files.",
  "requirements": ["Transcript text checked by the user"],
  "output": "Work notes with key points and action items.",
  "skills": []
}
```

Import the directory or archive through the solution import flow. The preparation checklist shows the model, catalog version, and current host state. `1.0.0` identifies the catalog resource version; DSH's native preparer still owns the actual weight version, hashes, and download verification. Initial preparation requires user confirmation in the existing settings page and is not an automatic download step in solution preparation.

| Condition | Behavior |
| --- | --- |
| A valid declaration refers to an unsupported catalog resource, version, or usage | The solution can still be imported; the declaration and its status remain visible |
| A required model is not ready | Only its dependent resource is blocked; other resources remain usable |
| An optional model is unavailable | The missing capability is shown without blocking the resource; developers must explain an alternative operation |
| Provider state is `ready` or `standby` | The model is usable; its service wakes a standby model on demand |
| A managed task or scheduled task is created or executed again | Dependencies are checked again instead of permanently caching readiness from creation time |
| Two solutions reference the same model | They use the same provider; uninstalling a solution does not delete shared weights |

Declarations are stored in existing fixed content and resource snapshots; current state comes from the corresponding provider service. An upgrade that changes the model ID, version, usage, or required flag needs explicit adoption of the candidate resource. The existing Keep option preserves local instances, not a previous model declaration. Cancel the upgrade to continue using the old dependencies. Both client and backend must enforce this choice.

The contract lives in `packages/contract/src/industry-model-dependencies.ts`; the backend owns content and fixed snapshots. According to catalog usage and binding, the Harness adapter in `industry-model-readiness.ts` discovers the active optional service through Cordis's public `ctx.reflect.get('speechToText')` or `ctx.reflect.get('teloaEmbedding')`, then reads `snapshot()` without mutation. A plugin scope without the injection cannot access `ctx.speechToText` directly. Reading status must not turn an optional extension into a required dependency. The preparation panel and task path reuse this check. Tasks, plans, and business actions recheck their already fixed content and resource versions before running again, without following the current solution or rebuilding the task.

Skill installation and its preview validate and fix the content without requiring a ready model or starting model preparation. Using a Skill through a solution checks that solution's declaration. Multiple solutions may share one public Skill; the first installation source must not impose its prerequisites globally.

When an ordinary native conversation reads a packaged Skill (`industry-local`), the provider’s `get` boundary rechecks model prerequisites against its fixed package source. Independent calls to publicly referenced Skills (`industry-public`) do not inherit a referencing solution’s extra prerequisites; the atomic Skill format has no model dependency field. Unavailable dependencies fail explicitly without falling back to another same-named skill. These checks do not cover content already in context or arbitrary third-party Skills.

The usage vocabulary includes `speech-to-text`, `text-to-speech`, `embedding`, `rerank`, `ocr`, `classification`, `extraction` and `chat`. A usage name does not establish a general provider adapter. New non-speech providers need locked-version model files, licensing, hardware requirements, tool permissions and quality evidence.

## Unified input and work execution

::: info Current release
Models, employee permissions and business data sources must be available. See the [Workbench guide](https://docs.teloa.ai/v/0.2.3/markdown/en/guides/workbench.md) and [Task guide](https://docs.teloa.ai/v/0.2.3/markdown/en/guides/tasks.md) for entry points.
:::

### Home and conversations share native input

The first submission from home creates or reuses the conversation for that request. The welcome area becomes the work conversation with the first message already submitted. Opening an existing conversation continues its context. Home does not require an upfront Chat/Work choice or another “insert into input” step after sending. The conversation remains available in recent work; formal tasks are created when needed.

Both surfaces reuse the DSH native composer, draft, and submission path, retaining text editing, `/` commands, Skills, `@` references, files, images, model selection, permissions, and voice input when available. Teloa adds business scope and business references through public slots and services. Do not copy the editor or maintain a reduced home textarea. Attachment, model, and voice capabilities still depend on the actual runtime configuration. Business appears immediately before Knowledge and capabilities in the native toolbar, without a persistent executor-preference selector. Ordinary chat retains its current assistant; delegation tools verify explicitly named employees, and existing assignee constraints remain visible.

The difference is the target context: a new conversation starts new work; an existing one continues it. Model selection applies to the current lead assistant by default and must not silently override employees or task assistants. Selecting a business or changing conversation permissions does not expand role authorization. The group composer retains group mentions, topics, and shared-attachment semantics rather than adopting the one-to-one layout.

Twin and employee one-to-one conversations use the native model menu. Their selection is stored in that conversation and used for both requests and image admission without changing the global default. Ordinary owner conversations retain DSH default-model persistence; formal role tasks use the primary and fallback policy fixed at Run creation. The host derives ownership from existing identity links and does not write global settings when ownership cannot be read. Only explicitly configured models are used as fallbacks, and switching outcomes are persisted. `teloa_model_prepare` requires owner confirmation in ordinary conversations; task sessions and sub-agents cannot initiate it. This is not automatic model planning and does not guarantee fallback service availability.

DSH's native Custom Model API already supports connecting to Ollama through a user-configured endpoint. Teloa adds marketplace resources, download confirmation and progress, weight and runtime-capacity verification, and employee/task model policies. Inference, tool execution, model selection, and message rendering continue to use DSH. Ollama is an optional, independent runtime. Its management code currently ships with Teloa without requiring users to install the runtime; it is not yet a separately switchable marketplace extension.

Local-model reasoning capabilities must come from official Ollama metadata and map to DSH's `reasoningEfforts`. The native adapter separates and renders reasoning and answer text. Do not assume that every Qwen model can disable reasoning or strip thinking tags from answers. Ollama 0.34.4 has been verified. When an older runtime lacks the required metadata for a reasoning model, downloaded weights are retained and reconnection requires an Ollama upgrade. Fitting a model in memory does not establish its quality on complex tasks; experimental catalog status remains subject to acceptance for each model.

### Lead assistant, employees, and tasks

The lead assistant handles general requests, selects suitable employees or organizes a task team when necessary, and summarizes outcomes for the user. A new conversation does not create a lasting employee. An explicitly named executor must be checked against duties, permissions, and active status. Show ownership only after the real execution service accepts the delegation; a prompt impersonating an employee is insufficient.

Work needing accountable ownership, continued tracking, and delivery becomes a formal task. Ordinary questions and one-off queries can finish in the conversation. Calling a tool alone does not justify creating a task. A conversation may relate to multiple tasks; Task/Run, native execution records, and work output records respectively maintain responsibility, execution facts, and delivery, linked as views of the same work.

| Request | Target behavior and evidence |
| --- | --- |
| Summarize today's work | Query real tasks, executions, and deliveries, stating scope and as-of time without waking every employee |
| Ask every employee for a fresh update | Collect new replies, distinguish received, waiting, and unavailable, and show a summary with expandable individual reports |
| Summarize SOC alerts over the past 30 days | Query the actual alert source and show dates, time zone, source, and coverage; task counts cannot substitute for alert counts |
| Investigate an incident in depth | Link the identified incident, owner, and managed execution; show actual steps, evidence, gaps, and the final report |

“All businesses” is a query perspective limited to what the user may access; “General work” is a business attribution. They are not the same authorization scope. Requests from SOC default to SOC. A summary request does not make private logs or role memories available to every agent. Formal tasks need explicit business ownership, and cross-business coordination does not expand permissions.

### Submission, recovery, and delivery

One user submission must link the same request, conversation, and any resulting task and execution. Duplicate clicks and retries reuse the original request. When a response is lost, reconcile the server outcome before attempting anything again. Failures before acceptance preserve the natively recoverable draft. If delegation fails after the message was accepted, the original message and work request remain for reconciliation and continuation; the consumed draft is not automatically restored. A late receipt must not clear newer edits or target another conversation. Local attachments that cannot survive a refresh must explicitly require reattachment.

Progress comes from actual execution facts. Paused work, missing configuration, partial failures, and pending approval must be visible. Approval applies to the specific action required by policy; sending a request does not authorize every subsequent action. Task-assistant completion does not replace business acceptance.

Deliverables return to the originating conversation or group topic and link to the task and incident. Group delivery also checks sharing boundaries. Ordinary responses use readable names and source links, with internal identifiers retained in trace details. Validation, draft protection, and recovery remain available for imports and conflicts; a preparation page is not a mandatory step for every normal submission.

### Implementation and boundaries

`HomeNativeConversation.tsx` wraps official `main.conversation`, reusing the complete native conversation, editor, and submission service. Home and existing conversations keep the same mounting position; `WorkHome.tsx` only provides the overview. A pending blank conversation has a stable identity and stays out of recent work before a message is sent. `BindingClient` saves business context or employee/task associations before opening a new conversation, preventing its first submission from using the wrong identity. Resource insertion checks the native draft version. `PreparedPromptCard.tsx` remains for imports and recovery.

`conversation-work.ts` persists trusted business context, the original user message, and the fixed delegation roster. `conversation-work-tools.ts` gives the owner's lead conversation tools for directory lookup, dispatch, fresh reports, status, stop, resume, work facts, and business queries. Identity comes from the actual conversation, not a model-supplied owner. `conversation-work-dispatch.ts` reuses existing task, role, material authorization, and Run services. Request, Task, and Run identities are fixed by the original message; resuming in a later turn keeps the same request. A coordinating conversation can continue coordinating after linking tasks. Dedicated role, task-execution, and native child conversations retain their own boundaries.

`HomeWorkRequestCard.tsx` reads server status and provides links to the original tasks plus stop/resume actions. `conversation-work-publisher.ts` appends verified replies as native notices to the originating conversation. Stable content is deduplicated, and one unavailable conversation does not block other results. Receiving an employee's reply is distinct from accepting the business deliverable.

Native files and images still use the current conversation's native submission path. **Delegation to a role in another conversation currently supports text and authorized Teloa resource references. Delegation containing uploaded attachments or other structured blocks is explicitly rejected before task creation; the original message remains.** Images are never silently reduced to filenames, and full attachment delegation is not claimed. Authorized file/image snapshots across roles still need integration. Real SOC queries require a configured business source. Integration tests using scripted models and synthetic alerts do not replace acceptance against a customer's real sources.

Assign tracked work to an AI employee or to the general Agent without creating an employee first. General tasks use owner execution authorization, a dedicated task conversation and a managed Run, retaining the original message, material and budget boundaries. Delegated work follows the authorization for that task. Receiving a reply does not by itself save a deliverable or complete business acceptance.

## Changing a field across packages

Update the contract and defaults first, then check backend storage, adapter parsing, client readers, and test fixtures. Parsers that accept only an exact set of keys may reject a new field. A type change alone does not establish runtime compatibility.

For a new task state, plan source, or reference, include at least one integration test using a real database and host, covering the full path from creation to display.

## Dependency direction

Keep database and UI dependencies out of pure contracts. Business services must not manipulate browser components directly, and clients must not bypass the adapter to write to the database. A new Harness can be designed around these boundaries, but the current public tutorials cover only the implemented DSH adapter.