> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# createVirtualWorkspace()

> **createVirtualWorkspace**(`ports`, `limits?`): [`ToolVirtualWorkspace`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#toolvirtualworkspace)

Persistent, actor-local text workspace over the existing private harness SQL
port. It intentionally exposes no filesystem, process, module-loading, or
dynamic-extension capability.

**Parameters**

| Parameter | Type |
| - | - |
| `ports` | [`AgentHarnessPorts`](/docs/agent-sdk/harness-sdk/ports) |
| `limits?` | [`VirtualWorkspaceLimits`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#virtualworkspacelimits) |

**Returns**
[`ToolVirtualWorkspace`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#toolvirtualworkspace)

## createVirtualWorkspaceTools()

> **createVirtualWorkspaceTools**(`workspace`): `Readonly`\<\{ `activate_skill`: `Tool`\<\{ `name`: `string`; }, [`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>; `edit_file`: `Tool`\<\{ `expectedRevision?`: `number` | `undefined`; `newText`: `string`; `oldText`: `string`; `path`: `string`; }, [`WorkspaceToolEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacetoolentry)>; `find_files`: `Tool`\<\{ `needle`: `string`; }, `Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `grep_files`: `Tool`\<\{ `needle`: `string`; }, `Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `list_files`: `Tool`\<`Record`\<`string`, `never`>, `Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `read_file`: `Tool`\<\{ `path`: `string`; }, `Readonly`\<\{ `bytes`: `number`; `content`: `string`; `origin`: `"workspace"`; `path`: `string`; `revision`: `number`; `truncated?`: `true`; } | \{ `found`: `false`; `origin`: `"workspace"`; `path`: `string`; }>>; `write_file`: `Tool`\<\{ `content`: `string`; `expectedRevision?`: `number` | `undefined`; `path`: `string`; }, [`WorkspaceToolEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacetoolentry)>; }>

Explicit server-side tools backed only by a [VirtualWorkspace](/docs/agent-sdk/harness-sdk/plug-ins/workspace). Skill
documents remain returned data; this factory never evaluates their content.

**Parameters**

| Parameter | Type |
| - | - |
| `workspace` | [`ToolVirtualWorkspace`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#toolvirtualworkspace) |

**Returns**
`Readonly`\<\{ `activate_skill`: `Tool`\<\{ `name`: `string`; }, [`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>; `edit_file`: `Tool`\<\{ `expectedRevision?`: `number` | `undefined`; `newText`: `string`; `oldText`: `string`; `path`: `string`; }, [`WorkspaceToolEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacetoolentry)>; `find_files`: `Tool`\<\{ `needle`: `string`; }, `Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `grep_files`: `Tool`\<\{ `needle`: `string`; }, `Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `list_files`: `Tool`\<`Record`\<`string`, `never`>, `Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `origin`: `"workspace"`; `truncated?`: `true`; }>>; `read_file`: `Tool`\<\{ `path`: `string`; }, `Readonly`\<\{ `bytes`: `number`; `content`: `string`; `origin`: `"workspace"`; `path`: `string`; `revision`: `number`; `truncated?`: `true`; } | \{ `found`: `false`; `origin`: `"workspace"`; `path`: `string`; }>>; `write_file`: `Tool`\<\{ `content`: `string`; `expectedRevision?`: `number` | `undefined`; `path`: `string`; }, [`WorkspaceToolEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacetoolentry)>; }>

| Tool | Effect |
| - | - |
| `read_file` | Reads a file, cut at `maxOutputBytes` and then marked `truncated`. |
| `write_file` | Writes a file. With `expectedRevision`, only while the file is at that revision. |
| `edit_file` | Replaces a text that occurs exactly once in a file, under the same guard. |
| `list_files` | Lists the files in path order. |
| `find_files` | Lists the files whose content contains a text. |
| `grep_files` | Returns the lines that contain a text, with their paths and line numbers. |
| `activate_skill` | Returns one skill's document as data. |

The results of the file tools carry `origin: "workspace"`, and the result of `activate_skill` carries `origin: "activated-skill"`. A path is relative, such as `notes/order.md`, and at most 128 bytes.

## read()

> **read**(`path`): `Promise`\<[`WorkspaceRead`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceread) | `undefined`>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |

**Returns**
`Promise`\<[`WorkspaceRead`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceread) | `undefined`>

## write()

> **write**(`path`, `content`, `options?`): `Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |
| `content` | `string` |
| `options?` | [`WorkspaceWriteOptions`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacewriteoptions) |

**Returns**
`Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

## edit()

> **edit**(`path`, `oldText`, `newText`, `options?`): `Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |
| `oldText` | `string` |
| `newText` | `string` |
| `options?` | [`WorkspaceWriteOptions`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacewriteoptions) |

**Returns**
`Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

## list()

> **list**(): `Promise`\<`Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**Returns**
`Promise`\<`Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

## find()

> **find**(`needle`): `Promise`\<`Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `needle` | `string` |

**Returns**
`Promise`\<`Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

## grep()

> **grep**(`needle`): `Promise`\<`Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `truncated?`: `true`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `needle` | `string` |

**Returns**
`Promise`\<`Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `truncated?`: `true`; }>>

## journal()

> **journal**(`options?`): `Promise`\<readonly [`WorkspaceJournalEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacejournalentry)\[]>

**Parameters**

| Parameter | Type |
| - | - |
| `options?` | `Readonly`\<\{ `limit?`: `number`; }> |

**Returns**
`Promise`\<readonly [`WorkspaceJournalEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacejournalentry)\[]>

## discoverSkills()

> **discoverSkills**(): `Promise`\<[`WorkspaceSkillCatalog`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceskillcatalog)>

**Returns**
`Promise`\<[`WorkspaceSkillCatalog`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceskillcatalog)>

A skill is the document at `skills/<name>/SKILL.md`, written like any other file. Nothing in a skill is executed.

## activateSkill()

> **activateSkill**(`name`): `Promise`\<[`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>

**Parameters**

| Parameter | Type |
| - | - |
| `name` | `string` |

**Returns**
`Promise`\<[`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>

## assemblePrompt()

> **assemblePrompt**(`base`, `skills`): `Promise`\<`Readonly`\<\{ `sources`: readonly [`PromptSource`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#promptsource)\[]; `text`: `string`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `base` | `string` |
| `skills` | readonly `string`\[] |

**Returns**
`Promise`\<`Readonly`\<\{ `sources`: readonly [`PromptSource`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#promptsource)\[]; `text`: `string`; }>>

## VirtualWorkspaceLimits

**Properties**
**maxFileBytes?**

> `readonly` `optional` **maxFileBytes?**: `number`

**maxOutputBytes?**

> `readonly` `optional` **maxOutputBytes?**: `number`

**maxResults?**

> `readonly` `optional` **maxResults?**: `number`

**maxWorkspaceBytes?**

> `readonly` `optional` **maxWorkspaceBytes?**: `number`

| Limit | Default | Bounds |
| - | - | - |
| `maxFileBytes` | 64 KiB | One file. |
| `maxWorkspaceBytes` | 1 MiB | Every file together. |
| `maxOutputBytes` | 16 KiB | One result, the assembled prompt included. |
| `maxResults` | 100 | The entries of one listing or search. |

## WorkspaceEntry

**Properties**
**bytes**

> `readonly` **bytes**: `number`

**path**

> `readonly` **path**: `string`

**revision**

> `readonly` **revision**: `number`

## WorkspaceRead

**Properties**
**bytes**

> `readonly` **bytes**: `number`

**content**

> `readonly` **content**: `string`

**path**

> `readonly` **path**: `string`

**revision**

> `readonly` **revision**: `number`

**truncated?**

> `readonly` `optional` **truncated?**: `true`

## WorkspaceWriteOptions

**Properties**
**expectedRevision?**

> `readonly` `optional` **expectedRevision?**: `number`

## WorkspaceJournalEntry

**Properties**
**bytes**

> `readonly` **bytes**: `number`

**operation**

> `readonly` **operation**: `"write"` | `"edit"`

**path**

> `readonly` **path**: `string`

**revision**

> `readonly` **revision**: `number`

**sequence**

> `readonly` **sequence**: `number`

## WorkspaceSkill

**Properties**
**name**

> `readonly` **name**: `string`

**origin**

> `readonly` **origin**: `"workspace"`

**path**

> `readonly` **path**: `string`

## WorkspaceSkillCatalog

**Properties**
**skills**

> `readonly` **skills**: readonly [`WorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceskill)\[]

**truncated?**

> `readonly` `optional` **truncated?**: `true`

## ActivatedWorkspaceSkill

**Properties**
**content**

> `readonly` **content**: `string`

**name**

> `readonly` **name**: `string`

**origin**

> `readonly` **origin**: `"activated-skill"`

**path**

> `readonly` **path**: `string`

## PromptSource

> **PromptSource** = `Readonly`\<\{ `origin`: `"application"`; }> | `Readonly`\<\{ `name`: `string`; `origin`: `"activated-skill"`; `path`: `string`; }>

## WorkspaceToolEntry

**Properties**
**bytes**

> `readonly` **bytes**: `number`

**origin**

> `readonly` **origin**: `"workspace"`

**path**

> `readonly` **path**: `string`

**revision**

> `readonly` **revision**: `number`

## ToolVirtualWorkspace

A concrete workspace that can atomically preflight tool mutation results.

**Properties**
**\[TOOL\_WORKSPACE\_CAPABILITY]**

> `readonly` **\[TOOL\_WORKSPACE\_CAPABILITY]**: `true`

**Methods**
**activateSkill()**

> **activateSkill**(`name`): `Promise`\<[`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>

**Parameters**

| Parameter | Type |
| - | - |
| `name` | `string` |

**Returns**
`Promise`\<[`ActivatedWorkspaceSkill`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#activatedworkspaceskill)>

**assemblePrompt()**

> **assemblePrompt**(`base`, `skills`): `Promise`\<`Readonly`\<\{ `sources`: readonly [`PromptSource`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#promptsource)\[]; `text`: `string`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `base` | `string` |
| `skills` | readonly `string`\[] |

**Returns**
`Promise`\<`Readonly`\<\{ `sources`: readonly [`PromptSource`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#promptsource)\[]; `text`: `string`; }>>

**discoverSkills()**

> **discoverSkills**(): `Promise`\<[`WorkspaceSkillCatalog`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceskillcatalog)>

**Returns**
`Promise`\<[`WorkspaceSkillCatalog`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceskillcatalog)>

**edit()**

> **edit**(`path`, `oldText`, `newText`, `options?`): `Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |
| `oldText` | `string` |
| `newText` | `string` |
| `options?` | [`WorkspaceWriteOptions`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacewriteoptions) |

**Returns**
`Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

**find()**

> **find**(`needle`): `Promise`\<`Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `needle` | `string` |

**Returns**
`Promise`\<`Readonly`\<\{ `matches`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**grep()**

> **grep**(`needle`): `Promise`\<`Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `truncated?`: `true`; }>>

**Parameters**

| Parameter | Type |
| - | - |
| `needle` | `string` |

**Returns**
`Promise`\<`Readonly`\<\{ `matches`: readonly \{ `line`: `number`; `path`: `string`; `text`: `string`; }\[]; `truncated?`: `true`; }>>

**journal()**

> **journal**(`options?`): `Promise`\<readonly [`WorkspaceJournalEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacejournalentry)\[]>

**Parameters**

| Parameter | Type |
| - | - |
| `options?` | `Readonly`\<\{ `limit?`: `number`; }> |

**Returns**
`Promise`\<readonly [`WorkspaceJournalEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacejournalentry)\[]>

**list()**

> **list**(): `Promise`\<`Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**Returns**
`Promise`\<`Readonly`\<\{ `entries`: readonly [`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)\[]; `truncated?`: `true`; }>>

**read()**

> **read**(`path`): `Promise`\<[`WorkspaceRead`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceread) | `undefined`>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |

**Returns**
`Promise`\<[`WorkspaceRead`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceread) | `undefined`>

**write()**

> **write**(`path`, `content`, `options?`): `Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>

**Parameters**

| Parameter | Type |
| - | - |
| `path` | `string` |
| `content` | `string` |
| `options?` | [`WorkspaceWriteOptions`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspacewriteoptions) |

**Returns**
`Promise`\<[`WorkspaceEntry`](/docs/agent-sdk/harness-sdk/plug-ins/workspace#workspaceentry)>