# TypeScript Map (Types + Hot Functions)

This doc is optimized for AI agents: it names the core TypeScript types and the handful of functions/methods that actually control behavior.

For runtime flow diagrams, see:

- `docs/architecture/AGENT_DIAGRAM.md`
- `docs/architecture/CONTRIBUTOR_MAP.md`

## Core Domain Types (What Matters)

### Messages

- `InboundMessage` / `OutboundMessage`
  - Used by channel adapters and the message router.
  - Source: `src/channels/types.ts`, `src/daemon/routing.ts`

### Tools

- `Tool`
  - A single capability callable by the model.
  - Source: `src/tools/types.ts`

- `ToolResult`
  - Return value from a tool.
  - Source: `src/tools/types.ts`

- `ToolPolicyContext`
  - Dynamic context used to decide tool availability and enforcement.
  - Source: `src/tools/policy.ts`

Key fields to know:

- `agent`, `provider`, `autonomyLevel`
- `skillName`, `skillPermissions`
- `executionEnvironment` (`host` or `sandbox`)
- `untrustedContent` (tightens guards after fetched content appears)

### Skills

- `SkillManifest`
  - `manifest.json` parsed and validated.
  - Source: `src/skills/types.ts`

- `SkillPermissions`
  - Capability declarations that get enforced at runtime.
  - Source: `src/skills/types.ts`

### Audit

- `AuditEventType` and tool events (`tool.start`, `tool.success`, `tool.denied`, `tool.approval`)
  - Source: `src/audit/types.ts`

## Hot Functions / Methods (Where Behavior Lives)

If you only read 10 definitions, read these:

- `createMessageRouter()`
  - Routes inbound messages, resolves intent targets (agent vs skill).
  - File: `src/daemon/routing.ts`

- `getOrCreateAgent()` (inner helper)
  - Builds per-session `AgentOrchestrator` and sets `toolPolicyContext`.
  - File: `src/daemon/routing.ts`

- `AgentOrchestrator.process()`
  - Runs the agent loop and streams output.
  - File: `src/backends/native/orchestrator.ts`

- `NativeAgent.toolLoop()`
  - The core loop: model -> tool calls -> tool results -> model -> final response.
  - Adds provenance markers to tool results.
  - File: `src/backends/native/agent.ts`

- `ToolPolicy.resolveAllowedNames()`
  - Computes the available tool set for a given context.
  - Enforces skill capability intersection (deny-by-default for skill context).
  - File: `src/tools/policy.ts`

- `ToolExecutor.execute()`
  - Defense-in-depth enforcement + hooks/autonomy + auditing.
  - Enforces skill fs/net/secret scope + injection guard.
  - File: `src/tools/executor.ts`

## Diagram: Key Types (Mermaid)

```mermaid
classDiagram
  class Tool {
    +string name
    +string description
    +JSONSchema inputSchema
    +string[]? requiredSecretScopes
    +execute(args): Promise~ToolResult~
  }

  class ToolResult {
    +boolean success
    +string output
    +string? error
  }

  class ToolPolicyContext {
    +string? agent
    +string? provider
    +string? autonomyLevel
    +string? sessionId
    +string? channel
    +string? sender
    +string? tier
    +string? skillName
    +SkillPermissions? skillPermissions
    +string? executionEnvironment
    +boolean? untrustedContent
    +string[]? allowedSecretScopes
  }

  class SkillManifest {
    +string name
    +string description
    +string version
    +string tier
    +SkillPermissions? permissions
  }

  class SkillPermissions {
    +string[]? tool_groups
    +string[]? tools
    +SkillFsPermissions? fs
    +SkillNetPermission[]? net
    +string[]? secrets
    +string? execution_environment
  }

  class AuditToolEvent {
    +string tool_name
    +string? execution_id
    +string? execution_environment
    +string? skill_name
    +number? redactions_applied
  }

  Tool --> ToolResult
  ToolPolicyContext --> SkillPermissions
  SkillManifest --> SkillPermissions
```

## Diagram: Control Flow (Tool Call Path)

```mermaid
flowchart TD
  A[Model proposes tool call] --> B[ToolPolicy filters allowed tools]
  B --> C[ToolExecutor.execute]
  C --> D{Allowed by policy?}
  D -- no --> X[Denied + audit]
  D -- yes --> E{Hooks/autonomy confirm?}
  E -- denied --> X
  E -- approved --> F{Skill constraints}
  F -- violation --> X
  F -- ok --> G{Untrusted content guard}
  G -- blocked --> X
  G -- ok --> H[Tool.execute]
  H --> I[Audit (redacted)]
  I --> J[ToolResult returned to model]
```

## Diagram: Module Entry Points

These are the places you typically jump to first.

```text
src/daemon/index.ts
  - wires together: config + skillRegistry + toolRegistry + toolExecutor + router

src/daemon/routing.ts
  - inbound routing + intent match + per-session agent construction

src/backends/native/agent.ts
  - tool loop (the actual "agent")

src/tools/policy.ts
  - tool allow/deny resolution (+ skill capability intersection)

src/tools/executor.ts
  - enforcement + hooks + auditing
```
