Workspace Capabilities

This guide maps the workspace capability architecture: what the system can do, which execution path owns each action, and how access is governed.

---

1. Capability Architecture

Workspace capabilities are organized into four layers:

• Policy Layer: Defines audience, risk, defaults, and aliases for each tool.
• Runtime Layer: Builds the available toolset for each agent and actor.
• Execution Layer: Runs tools in chat, workflows, or background phantom tasks.
• Governance Layer: Enforces owner/visitor boundaries, SQL safety, and write restrictions.

---

2. Owner Control Plane

Owner-only capabilities provide control over operations, settings, and review workflows:

• fetchInbox: Read pending/resolved inbox entries tied to the agent.
• resolveInboxItem: Mark inbox items as resolved with optional notes.
• listAvailableTools: View platform tools available for policy enablement.
• getAgentSettings / updateAgentSettings: Read and update behavior settings.

These tools are part of the owner control plane and are blocked for visitor sessions.

---

3. Workflow Execution Plane

Workflow capabilities let owners turn instructions into repeatable background execution:

• createWorkflow
• updateWorkflow
• fetchWorkflows
• triggerWorkflow

Workflows run through the shared orchestration path and can produce inbox alerts, summaries, spreadsheets, and documents.

---

4. Web Intelligence Plane

Web tools are aligned across interactive chat and background workflows:

• webSearch: Multi-provider cascade:

1. Firecrawl (primary)

2. Jina (fallback)

3. Legacy Supabase web-search fallback

• webScrape: Deep page reading with browser-first extraction and fallback fetch.

Use this plane when the agent needs current external information or must inspect a specific URL.

---

5. B2B Search & Prospecting Plane

B2B contact and company directory prospecting tools:

• b2bSearchPeople: Search for professional contacts, prospective leads, and people profiles using search queries, keywords, job titles, locations, company domains, and seniorities.
• b2bSearchOrganizations: Search for company profiles, organizations, and business structures using company name, domains, locations, employee ranges, and industries.
• b2bGetContactDetails: Retrieve full verified contact details, social links, and email/phone info for a contact by contact ID or email address.

---

6. Data and Sandbox Plane

Owner-scoped data tools are wired from the shared sandbox builder:

• runSQL: Read-only SQL querying (SELECT / WITH) with validation.
• executeCode: Restricted JavaScript execution for calculations and transformations.
• analyzeData: Read-only analytical SQL with automatic numeric summaries (min, max, avg, sum, count).

---

7. Shared Registry Design

The registry is designed to prevent drift between what policy exposes and what runtime can execute:

• Missing references were implemented or removed.
• The shared buildPhantomTools path now acts as a single source of truth for workflow tool execution.
• Sandbox tools are assigned as a complete group instead of partial/manual references.

---

8. Governance Boundaries

• Tool policy lives in the worker and cannot be bypassed from UI text.
• Owner-only tools remain inaccessible to visitors.
• Write/admin operations are policy-gated and role-checked.
• SQL pathways are restricted to non-mutating queries.

---

9. Recommended Operating Pattern

1. Use b2bSearchPeople + b2bSearchOrganizations to find B2B prospects and organizations natively.

2. Use webSearch + webScrape for external research requests.

3. Use runSQL + analyzeData for internal metrics and trend analysis.

4. Use createWorkflow / triggerWorkflow for repeated reporting tasks.

5. Route outcomes to inbox via reporting flows for owner review.

This pattern keeps execution auditable and consistent across interactive and background tasks.