This package ships six starter definitions used by the hub and demo experiences. Each definition contains a typed ID, name, role, glyph, color, mode, scopes, model label, prompt, and enablement flag. These are configuration data. This package does not run an LLM, load a model, execute tools, or authenticate callers; local:small is a model label for a consumer to resolve. The hub owns runtime behavior.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @smarthome.exchange/agents

Usage

import { getReferenceAgentById, referenceAgents } from '@smarthome.exchange/agents';

for (const agent of referenceAgents) {
  console.log(`${agent.name}: ${agent.role} (${agent.mode})`);
}

const comfortAgent = getReferenceAgentById('comfort');
console.log(comfortAgent?.scopes);

Starter Agents

Agent	Mode	Role	Default scopes
`comfort`	`auto`	Climate, light, ambience	Climate and light reads/writes plus device reads.
`sentinel`	`ask`	Locks, cameras, presence	Lock reads/writes, camera reads, and device reads.
`watt`	`ask`	Energy, solar, EV, appliances	Energy reads/writes, climate reads, and device reads.
`dawn`	`auto`	Wake, wind-down, daily ritual	Light reads/writes and device reads.
`echo`	`suggest`	Audio, media, follow-me	Device reads only.
`steward`	`ask`	Errands, deliveries, household ops	Device reads only.

Defaults use explicit capability scopes and never include wildcard reads, generic device.write, approval decisions, automation writing, or agent delegation. Sentinel has no alarm scope because the current device capability contract has no alarm capability. Watt and Dawn have no generic device writes; their broader persona descriptions do not grant unrelated effects. Echo can suggest media actions without a write grant, and Steward can coordinate without approval-decision authority.

Scopes and modes describe intended restrictions; they do not grant access by themselves. A trusted runtime must authenticate callers, bind them to a home, intersect an agent's configured scopes with trusted grants, and enforce tool scopes and modes. auto requests immediate permitted execution, ask requests approval before permitted effects, and suggest requests suggestions without effects. A prompt or an enabled flag is not authorization.

This package consumes @smarthome.exchange/interfaces 2.0.0. Its shared agent definition, mode, and scope types remain unchanged. Reference definitions are independent of a home; a runtime owns their registration in a selected home and its verified access grants. Every hub request requires context: { homeId }. Approval actions bind both subjectId and subjectKind from the verified identity, and approval decisions identify the reviewed expectedActionDigest. This configuration package constructs neither request envelopes nor approval actions or decisions.

Public API

Export	Purpose
`referenceAgents`	Readonly default roster; the array, definitions, and nested scope arrays are frozen.
`createReferenceAgents()`	Returns a new mutable roster with an independent scope array for each definition.
`getReferenceAgentById(agentId)`	Returns an independent mutable definition or `undefined` for an unknown ID.
`TReferenceAgentId`	Union of the six reference IDs. Custom runtime agents may use other IDs in the shared `IAgentDefinition` contract.
`IReferenceAgentDefinition`	Shared agent definition with a reference ID and the shared `TAgentMode` mode contract.
`TReadonlyReferenceAgentDefinition`	Readonly definition, including its scope array, used by the default roster.

Customizing Agents

Use the copy accessors to customize definitions for an application configuration or registry. Changing a returned definition, its scopes, or its roster cannot change the defaults or another consumer's copies. The exported referenceAgents defaults are readonly; migrate code that mutates that array to createReferenceAgents(). This package does not register definitions automatically.

import { createReferenceAgents } from '@smarthome.exchange/agents';

const localAgents = createReferenceAgents();
const sentinel = localAgents.find((agentArg) => agentArg.id === 'sentinel');
if (sentinel) {
  sentinel.systemPrompt += ' Always explain security-sensitive actions before requesting approval.';
}

Scripts

pnpm test
pnpm build
pnpm buildDocs

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@smarthome.exchange/agents