# HSM-II as an Action Layer

HSM-II is not just a chat runtime. It is also the layer that lets an LLM-backed agent take real-world actions in a controlled, observable way.

## Core purpose

Turn intent into action without turning your agent runtime into an unstructured pile of API wrappers, session hacks, and shell glue.

In practice, HSM-II sits between the model and the outside world:

- It exposes LLM-callable tools for common action surfaces.
- It can register external HTTP MCP tools from plugin manifests.
- It handles auth and policy checks around those calls.
- It keeps execution observable through task trail, harness events, and Company OS telemetry.
- It gives long-running agents a durable context recovery path instead of assuming session state survives forever.

## What HSM-II provides today

| Feature | What it does in HSM-II today |
|---|---|
| Built-in tool layer | Rust-native tools for web search, browser actions, file operations, shell, git, HTTP/data utilities, text processing, calculations, and maildir/email workflows |
| MCP tool bridge | Registers HTTP MCP tools on the personal-agent tool registry from plugin manifests and can optionally discover them via `tools/list` |
| Tool discovery | Tool schemas and descriptions are exposed to the model through the `ToolRegistry`, and Company OS also exposes tool discovery/describe surfaces |
| Authentication | API keys, JWTs, permission scopes, tenant-aware claims, and rate limiting for API consumers; connector auth headers for MCP/connector calls |
| Sessions and context | Harness run envelopes, thread workspaces, context repo manifests, task trail, and Company OS overview/context endpoints for deterministic re-entry |
| Sandbox and workspaces | Thread-scoped workspaces, VM overlay support, Docker-backed bash isolation, optional host isolation, and executor integration for stricter command execution paths |
| Triggers and scheduling | Heartbeats, scheduler jobs, webhook-style tools, and Company OS task orchestration hooks |
| Observability | Harness JSONL logs, runtime activity/events, task trail, governance events, spend tracking, and Company OS operator APIs |

## Important accuracy note

HSM-II is not currently a drop-in equivalent of Composio's hosted catalog model.

What the repo supports today is:

- A substantial built-in tool surface in Rust.
- Plugin-manifest-driven HTTP MCP tool registration.
- Company OS and personal-agent orchestration around those tools.

What the repo does not prove today as a shipped product capability:

- A hosted catalog of "1000+ toolkits".
- Universal white-label OAuth flows for third-party SaaS apps across that catalog.
- A managed hosted workbench product with remote multi-tenant session brokering in the Composio sense.

If we describe HSM-II publicly as an action layer, we should stay precise: it is a self-hostable agent runtime with a real tool plane, not yet a massive hosted integration marketplace.

## Two integration modes

### 1. Native HSM-II tools

This is the primary mode inside the repo today.

Agents use the Rust-native tool registry and call tools such as:

- `bash`, `grep`, `find`
- `read_file`, `write_file`, `edit_file`
- `git_status`, `git_diff`, `git_commit`, `git_push`
- `browser_navigate`, `browser_click`, `browser_type`, `browser_screenshot`
- `http_request`, `json_parse`, `csv_parse`, `webhook_send`
- Company OS tools such as `company_memory_search`, `company_create_task`, `company_tool_discover`

This mode is best when:

- You are running the personal agent or Company OS directly.
- You want tight control over policies, task trail, and workspace isolation.
- You want the tool surface versioned in the same Rust codebase as the agent runtime.

### 2. MCP-backed tools

HSM-II can also register HTTP MCP tools from plugin manifests through the MCP bridge.

This mode is best when:

- You already have an MCP server exposing tools.
- You want to connect external tool providers without hand-writing each tool in Rust.
- You want HSM-II to treat remote tools as first-class model-callable functions through the same registry.

This is the closest HSM-II gets today to a universal integration layer pattern.

## Who this is for

- Teams building long-running agents that need to do real work, not just generate text.
- Developers who want tools, policy gates, context recovery, and auditability in one runtime.
- Operators who need governance, spend tracking, and failure visibility around agent actions.
- Builders using Company OS as the orchestration layer for task-based agent execution.

## Mental model

Think of HSM-II as:

- a multi-agent operating system,
- plus a self-hostable tool plane,
- plus context recovery and observability,
- plus governance around execution.

It is not just "function calling." The design goal is to make tool use durable and inspectable across long horizons.

## Typical flow

### Personal-agent / Company OS flow

1. Start the runtime.
2. Load or create the company/task context.
3. Build the active tool registry.
4. Let the agent call native tools or registered MCP tools.
5. Record results in task trail, memory, governance, and spend surfaces.
6. Re-enter through Company OS overview or task context if the run crashes or the context window flushes.

### MCP extension flow

1. Define or install a plugin manifest for an MCP provider.
2. Point HSM-II at the provider endpoint.
3. Let the MCP bridge register tools, optionally discovering them with `tools/list`.
4. Apply connector policy and auth headers.
5. Use the exposed tools through the same tool registry as native tools.

## Where to look in the codebase

- Built-in tools: [`src/tools/mod.rs`](../src/tools/mod.rs)
- Tool registry: [`src/tools/registry.rs`](../src/tools/registry.rs)
- HTTP MCP bridge: [`src/tools/mcp_bridge.rs`](../src/tools/mcp_bridge.rs)
- API auth and rate limiting: [`src/auth.rs`](../src/auth.rs)
- Harness runtime and workspace isolation: [`src/harness/mod.rs`](../src/harness/mod.rs)
- Company OS ops overview and context recovery: [`docs/company-os/ops-overview-api.md`](./company-os/ops-overview-api.md)
- Company OS connector product layer: [`docs/company-os/connectors-sessions-and-triggers.md`](./company-os/connectors-sessions-and-triggers.md)

## Positioning guidance

If we want short external-facing copy, this is the honest version:

> HSM-II is a Rust-based multi-agent operating system with a built-in action layer. It gives LLM agents native tools, MCP-connected tools, policy gates, durable context recovery, and execution observability so they can take real-world actions safely over long-running tasks.