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.

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 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. The local retrieval implementation adds a strict teloa-embedding / qwen3-embedding-0.6b contract binding; integration with the production official catalog is still pending. 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

Capability and catalog status

The local retrieval extension is included in the alpha.7 source and disabled by default. Its runtime and model require separate preparation. Integration with model resources in the production official catalog is incomplete, and third-party provider installation is not open. A retrieval implementation does not make arbitrary marketplace models installable.

@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.

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

Protocol scope

Alpha.7 supports 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:

{
  "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:

{
  "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

Current release

This section covers unified input and managed delegation in alpha.7. Models, employee permissions and business data sources must be available. See the Workbench guide and Task guide 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.

Formal delegation currently requires a real employee. The lead assistant handles general work natively; a managed Run for a self-owned Task and automatic child work from task-specific conversations have not been added. Fresh reports use a persisted batch and member tasks without an additional parent Task. Replies are not automatically saved as work outputs or accepted as completed business work. Native draft persistence retains canonical resource-reference text after refresh, but does not restore reference-chip styling or temporary local attachments.

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.