# Agent Context Projection in OpenWork: How AI Agents See Your Workspace

> Understand agent context projection in OpenWork. Learn how AI agents discover and utilize your workspace tools for enhanced functionality and performance.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: deep-dive
- Published: 2026-07-31

---

**Agent context projection is the mechanism that captures a snapshot of available workspace tools, queries the underlying MCP provider for concrete capabilities, and normalizes the response into a typed structure that AI agents can consume to determine which tools are available, missing, or limited.**

Agent context projection forms the bridge between a user's workspace configuration and the AI agents that operate within it. In the OpenWork framework (`different-ai/openwork`), this feature aggregates extension capabilities, validates them against the provider's advertised tools, and surfaces any discrepancies to the agent runtime. By implementing a structured projection pipeline in TypeScript, OpenWork ensures that remote assistants receive accurate, up-to-date context about the tools they can invoke.

## What Is Agent Context Projection?

**Agent context projection** is the three-stage pipeline responsible for manifesting the current workspace state into a format consumable by AI agents. Unlike static configuration files, this projection dynamically evaluates which tools are actually present, which are advertised by the **Model Context Protocol (MCP)** provider but missing, and whether any limitations or errors prevent tool execution. The system exposes this information through the `/health` and `/reconcile` endpoints, allowing agents to adapt their behavior before attempting tool calls.

## Core Implementation

The implementation spans the TypeScript type definitions in `packages/types` and the health-check orchestration in `apps/server`.

### Deriving Logical Projections

The pipeline begins by transforming raw workspace objects into searchable projection metadata. In [`packages/types/src/den/connect-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/connect-diagnostics.ts), the **`deriveProjection`** function accepts an object—such as a plugin or connector—and generates a standardized projection containing a `title`, `description`, and `searchText` derived from the object's type and value.

```typescript
// Located in packages/types/src/den/connect-diagnostics.ts
const proj = deriveProjection({
  objectType: 'plugin',
  value: { id: 'my-plugin', name: 'My Plugin' }
});
// Returns: { title: 'My Plugin', description: '...', searchText: 'my-plugin ...' }

```

This logical projection serves as the foundation for downstream provider queries, ensuring that each tool or extension is represented by consistent, queryable metadata.

### Capturing Provider Snapshots

Once logical projections are established, OpenWork queries the MCP provider to determine which tools are actually available. The response conforms to the **`ProviderProjectionSnapshot`** interface, defined in [`packages/types/src/den/provider-projection.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/provider-projection.ts). This snapshot captures the ground truth from the provider with the following fields:

- **`source`**: Origin identifier of the projection request.
- **`checked`**: Boolean indicating whether the provider was successfully queried.
- **`provider`** and **`model`**: Identifiers for the specific provider and model configuration.
- **`present`**: Array of tools confirmed to be available.
- **`missing`**: Array of tools advertised in the logical projection but not found on the provider.
- **`limitation`**: Optional string describing partial capability restrictions.
- **`error`**: Optional error message if the provider query failed.

### Normalizing Tools for the Agent

The final stage translates the raw `ProviderProjectionSnapshot` into a consumable view. In [`apps/server/src/cloud-mcp-health.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-health.ts), the function **`experimentalProviderToolsFromProjection`** performs this normalization, returning a **`CloudMcpExperimentalProviderToolsSnapshot`** object.

This function handles three critical responsibilities:

1. **Missing Tool Resolution**: Flags tools listed in `missing` so the agent knows not to invoke them.
2. **Error Propagation**: Surfaces any provider-side errors stored in the `error` field.
3. **Capability Flagging**: Sets the **`includesMcpTools`** boolean to indicate whether the projection contains valid MCP tool definitions or should be considered untrustworthy.

```typescript
// Located in apps/server/src/cloud-mcp-health.ts
const mcpTools = experimentalProviderToolsFromProjection(providerSnap);
// Returns: { present: [...], missing: [], limitation?: string, error?: string, includesMcpTools: boolean }

```

## Health Checks and Error Handling

When the projection reveals discrepancies—such as `provider_tool_projection_missing` or `provider_projection_unavailable`—the health-checking routine records a structured failure object. This object includes a `stage: "provider_projection"` identifier and a specific error code, which is then exposed via the **health** and **reconcile** API endpoints.

The system distinguishes between:
- **Missing tools**: Tools defined in the workspace but not returned by the provider.
- **Provider errors**: Complete failure to reach or authenticate with the provider.
- **Limitations**: Partial availability where the provider supports the tool but with restricted functionality.

These states are rigorously validated in the test suite, specifically in [`apps/server/src/cloud-mcp-health.test.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-health.test.ts) and the end-to-end scenarios in [`apps/server/src/cloud-mcp-reconcile.e2e.test.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-reconcile.e2e.test.ts).

## Practical Implementation Example

The following example demonstrates the complete flow from logical derivation to normalized MCP tools:

```typescript
import { deriveProjection } from '@/packages/types/src/den/connect-diagnostics';
import { experimentalProviderToolsFromProjection } from '@/apps/server/src/cloud-mcp-health';

// Stage 1: Derive logical projection for a workspace extension
const logicalProj = deriveProjection({
  objectType: 'connector',
  value: { id: 'slack-connector', name: 'Slack Integration' }
});

// Stage 2: Assume providerSnap is fetched from MCP provider
const providerSnap = {
  source: 'openai',
  checked: true,
  provider: 'openai',
  model: 'gpt-4o',
  present: ['slack_post_message'],
  missing: ['slack_archive_channel'],
  limitation: undefined,
  error: undefined
};

// Stage 3: Normalize for agent consumption
const agentView = experimentalProviderToolsFromProjection(providerSnap);
// agentView.includesMcpTools === true
// agentView.missing contains 'slack_archive_channel'

```

## Summary

- **Agent context projection** dynamically maps workspace tools to provider capabilities through a typed TypeScript pipeline.
- The **`deriveProjection`** function in [`packages/types/src/den/connect-diagnostics.ts`](https://github.com/different-ai/openwork/blob/main/packages/types/src/den/connect-diagnostics.ts) creates searchable metadata from workspace objects.
- **`ProviderProjectionSnapshot`** captures the provider's ground truth, including present tools, missing tools, and errors.
- **`experimentalProviderToolsFromProjection`** in [`apps/server/src/cloud-mcp-health.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-health.ts) normalizes snapshots for agent consumption and sets reliability flags.
- Failure modes—such as missing tools or provider errors—are recorded with specific error codes and exposed through health endpoints to inform agent decision-making.

## Frequently Asked Questions

### What triggers an agent context projection update?

OpenWork refreshes the projection whenever the workspace configuration changes—such as when a new extension is installed—or when the health-check endpoint is polled. The system calls the MCP provider's `/experimental/tool` endpoint to ensure the snapshot reflects the current provider state.

### How does OpenWork handle missing tools in a projection?

When a tool appears in the logical projection but is absent from the provider's response, it is populated in the `missing` array of the `ProviderProjectionSnapshot`. The **`experimentalProviderToolsFromProjection`** function propagates this list to the final snapshot, allowing agents to disable or hide unsupported functionality rather than attempting failed invocations.

### What distinguishes `deriveProjection` from `experimentalProviderToolsFromProjection`?

**`deriveProjection`** operates on static workspace metadata to create a logical, searchable representation of a tool or extension. **`experimentalProviderToolsFromProjection`** operates on the dynamic response from the MCP provider, validating which logical tools actually exist and surfacing provider-specific errors or limitations.

### Where are projection failures recorded in the OpenWork architecture?

Failures are captured in the health-check orchestrator within [`apps/server/src/cloud-mcp-health.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-health.ts). The system generates failure objects with a `stage` property set to `"provider_projection"` and specific error codes like `provider_tool_projection_missing`. These records are exposed via the `/health` and `/reconcile` endpoints and are validated by the test suites in [`apps/server/src/cloud-mcp-health.test.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-health.test.ts) and [`apps/server/src/cloud-mcp-reconcile.e2e.test.ts`](https://github.com/different-ai/openwork/blob/main/apps/server/src/cloud-mcp-reconcile.e2e.test.ts).