Company OS and AgentChat operator guide

Company OS is the local-first operating spine for HSM-II. It gives a company one place to keep work, agents, memory, files, governance, spend, traces, and execution evidence.

AgentChat is the operator front door. You talk to it like a teammate, but consequential work is routed through Company OS tasks, worker runs, tools, and audit records instead of staying as loose chat.

This guide is for operators and builders who want to know:

• what HSM-II Company OS can do today
• how to run it locally
• how to integrate it with a company workspace
• how it helps a company operate with agents
• what is still optional, experimental, or human-gated

Short version

Run the workspace:

bash scripts/company-os-agentchat-ready.sh

Open:

• Workspace and AgentChat: http://127.0.0.1:3050/workspace/start
• Company OS API: http://127.0.0.1:3847
• API health: http://127.0.0.1:3847/api/company/health

Use Company OS when you want agent work to become durable company work:

1. Put the work in AgentChat or a task.
2. Attach relevant files, memory, connector context, or customer evidence.
3. Let AgentChat route it through the Company OS worker and tools.
4. Review the run, evidence, task, owner, and governance state.
5. Promote useful results into tasks, memory, skills, policies, or follow-up work.

What Company OS is

Company OS is not just a chatbot. It is a company control plane with a local Postgres-backed ledger.

Core parts:

Part	What it does
Company Console	Human workspace for AgentChat, tasks, files, runs, agents, costs, approvals, and dashboards.
hsm_console API	Rust/Axum API for Company OS records, worker execution, memory, tools, governance, traces, and health.
Postgres world model	Canonical storage for companies, tasks, goals, agents, runs, memory, connectors, policies, artifacts, and eval state.
AgentChat	Operator chat surface that can route substantive work into worker execution.
Native worker	ReAct-style execution loop with tools, finalization, evidence, and policy-aware behavior.
Company tools	Typed tools for memory, tasks, files, retrieval, sidecar providers, snapshots, connectors, and company records.
Governance and eval	Human gates, policy, run telemetry, trace capture, verifier checks, and promotion hooks.

The simple mental model:

operator intent -> AgentChat -> task / run -> tools + evidence -> Company OS ledger -> operator decision

What it can do today

Capability	How to use it	Why it matters
Start a company workspace	Run scripts/company-os-agentchat-ready.sh, then open /workspace/start.	Gives operators one entry point instead of scattered scripts.
Chat with an operator agent	Use AgentChat in Company Console.	Turns vague requests into tasks, plans, evidence, and runs.
Create and manage work	Use tasks, goals, agent runs, and task notes.	Keeps work durable across restarts and context loss.
Use files as evidence	Upload or ingest workspace files.	Lets agents cite company documents instead of guessing.
Use company memory	Store and retrieve scoped memory.	Keeps reusable context outside the prompt.
Route work to agents	Use agent roster, capability signals, DRI policy, and worker dispatch.	Makes ownership and routing explainable.
Govern risky work	Use approvals, human-required gates, governance events, and policy modes.	Stops sensitive work from silently mutating state.
Connect external systems	Use connector templates, connector accounts, sessions, triggers, and OpenAPI/MCP ingestion.	Lets agents act through real company accounts with auditability.
Track cost and runtime	Use spend events, runtime badges, run events, and eval/harness outputs.	Helps operators control quality, latency, and spend.
Evaluate and promote improvements	Use eval runs, verifier evidence, trace-to-skill promotion, and policy deltas.	Prevents "it worked once" from becoming unreviewed automation.

What AgentChat does

AgentChat should feel simple to the operator:

Ask -> clarify if needed -> route -> execute or escalate -> cite evidence -> update work

Under the hood, important turns can:

• classify the request
• create or update a Company OS task
• attach a turn plan
• route to an agent or DRI owner
• call typed Company OS tools
• persist useful evidence artifacts
• stream execution events
• write task notes or run records
• ask for human review when policy requires it

AgentChat should not expose that machinery in normal answers. Operators should see clean answers, next actions, evidence links, and approval needs.

Work modes

Use these modes as a practical guide:

Mode	Use it for	Expected behavior
Casual chat	Quick explanation, brainstorming, simple summaries.	Lightweight answer. No heavy routing unless needed.
Workspace work	Tasks, documents, planning, research, internal coordination.	Create or update durable work records when useful.
Consequential work	Customer impact, finance, legal, HR, infrastructure, compliance, policy, spend.	Require dri_key or no_dri_reason, evidence, and a clear owner.
High-risk action	Writes to customer systems, money movement, policy changes, sensitive data, deployment, destructive actions.	Require human approval unless explicit policy allows automation.
Power mode	Tuning routing, providers, harnesses, policies, evals, costs, and advanced automation.	Require signed operational deltas and evidence IDs for mutations.

The default product should be Workspace, not Power. Power is for operators tuning the system, not for every employee.

How to use it

1. Start the stack

bash scripts/company-os-agentchat-ready.sh

If ports are stale during local development:

bash scripts/company-os-agentchat-ready.sh --restart

Lower-level launcher:

bash scripts/company-os-up.sh

2. Open the workspace

Open:

http://127.0.0.1:3050/workspace/start

Use the first-run flow to choose a company, inspect runtime status, and open AgentChat.

3. Give AgentChat real company context

Good prompts:

• "Create a task for the broken onboarding email flow and assign the right owner."
• "Review this customer complaint, find the likely product area, and draft the next action."
• "Summarize this contract and tell me what needs legal review."
• "Look at current tasks and tell me the highest leverage next work."

Better prompts include:

• customer or project name
• deadline or urgency
• relevant file or URL
• allowed action level
• who should approve sensitive changes

4. Review the run

After a serious turn, check:

• task or goal created
• owner or DRI reason
• evidence artifacts
• tool calls or run events
• governance status
• final outcome and next action

5. Promote only what is proven

Useful outputs can become:

• task updates
• memory entries
• native sidecar records
• connector sessions or triggers
• eval evidence
• skill proposals
• runtime policy deltas

Do not promote raw chat vibes. Promote evidence-backed artifacts.

How to integrate a company

Think of integration as layers. Do the top layers first.

Layer 1: Company record

Create or select the company in Company Console. This gives every record a company_id.

Company-scoped records include:

• tasks and goals
• agents and agent runs
• memory
• files and artifacts
• connectors and credentials
• governance events
• spend events
• eval and promotion records

Layer 2: Work model

Define how the company thinks about work:

• common task types
• teams or domains
• DRI assignments
• approval rules
• high-risk categories
• recurring workflows

Keep this simple. A useful initial model is:

domain -> owner/DRI -> allowed actions -> approval required? -> evidence required?

Layer 3: Documents and memory

Add the documents agents need to avoid guessing:

• product docs
• customer docs
• policies
• runbooks
• contracts
• meeting notes
• support transcripts

Use workspace files and memory so AgentChat can cite company-owned context.

Layer 4: Connectors

Connect real systems only when there is a clear workflow:

• CRM or customer support
• calendar and email
• issue tracker
• repository and CI
• finance tools
• HR tools
• cloud or infrastructure dashboards

Company OS has connector templates, connector accounts, sessions, trigger subscriptions, and OpenAPI/MCP ingestion. Treat connectors as permissioned company accounts, not generic API keys floating in prompts.

Layer 5: Governance

Define what needs a human:

• legal, HR, finance, compliance
• customer-facing actions
• production infrastructure
• destructive changes
• spend increases
• policy changes

For consequential work, AgentChat should explain:

Owner X because domain Y matched evidence Z under policy mode M.

Layer 6: Evals and improvement

Add evals only where they change decisions:

• Does AgentChat route correctly?
• Does it create the right task?
• Does it cite evidence?
• Does it escalate risky work?
• Does it stay lightweight for casual chat?

Use eval evidence to tune routing, policy, and prompts. Avoid running expensive evals just to collect activity logs.

How this helps a company

Company OS is useful when work is falling between people, tools, and chat threads.

It helps by making agent work:

• durable: work survives context loss and restarts
• owned: tasks have owners, DRI policy, and escalation paths
• auditable: runs, tools, evidence, and governance events are recorded
• grounded: answers cite company files, memory, and artifacts
• reviewable: risky actions can require human approval
• measurable: evals and traces show whether workflows are improving
• integratable: connectors let agents act through company systems
• less chaotic: operators see one workspace instead of many disconnected tools

The practical promise is not "replace every employee." The useful promise is:

fewer dropped tasks, faster internal coordination, better evidence, clearer ownership, and safer automation

Best-fit companies

HSM-II Company OS is most useful for:

• small teams with too many operational threads
• agencies managing repeated client workflows
• devtools or SaaS teams with support, engineering, docs, and release loops
• founder-led companies that need leverage without losing oversight
• internal AI ops teams evaluating agent workflows
• compliance-sensitive teams that need audit trails before automation

It is less useful for:

• teams that only need a simple chatbot
• companies without repeatable workflows
• companies unwilling to define owners and approval policy
• high-risk regulated work where no local automation is allowed

What to keep simple

The product should default to a minimal operator path:

Workspace -> AgentChat -> Tasks -> Evidence -> Approval when needed

Do not make every user choose between harnesses, model lanes, sidecars, eval packs, and graph views. Those are advanced controls.

Default surfaces:

• Start
• Chat
• Tasks
• Files
• Approvals
• Runs
• Costs

Advanced surfaces:

• Power mode
• eval harnesses
• provider routing
• sidecar providers
• semantic routing
• trace-to-skill promotion
• policy deltas

Honest boundaries

Company OS currently has a strong local-first spine, but advanced lanes should stay explicit:

• Optional providers and sidecars extend the system; they are not the canonical source of truth.
• Postgres Company OS records are canonical.
• Risky work should be human-gated unless policy explicitly allows autonomy.
• Evals should prove behavior before promotion.
• DRI routing should create evidence for consequential work.
• AgentChat should not claim a tool, connector, memory, or sidecar result unless it has evidence.
• Power mode should mutate behavior only through signed operational deltas and evidence artifact IDs.

Core references

• Launch guide: docs/company-os/COMPANY_OS_AGENT_CHAT_LAUNCH.md
• Action layer: docs/HSMII_ACTION_LAYER.md
• Connectors and triggers: docs/company-os/connectors-sessions-and-triggers.md
• World model and intelligence: docs/company-os/world-model-and-intelligence.md
• DRI and intelligence alignment: docs/company-os/intelligence-layer-dri-alignment.md
• Eval and meta-harness: docs/EVAL_AND_META_HARNESS.md
• Agent skills: docs/AGENT_SKILLS.md

Copy for LLM

You are working in the HSM-II monorepo.

Before changing Company OS or AgentChat, read:
- docs/company-os/HSM_II_COMPANY_OS_OPERATOR_GUIDE.md
- docs/company-os/COMPANY_OS_AGENT_CHAT_LAUNCH.md
- docs/HSMII_ACTION_LAYER.md

Deliverable:
1. Explain which Company OS records or APIs the change touches.
2. Explain whether AgentChat should stay lightweight or create durable work.
3. Explain what evidence, owner, DRI, approval, or eval proof is required.
4. List the command or test that proves the behavior.