# Shared Actions

Arguments and follow-up steps for connection, sync, browser, and sharing operations.

Call a fixed product Action through `indra.action` with `{"name":"…","params":{…}}`. For an operation that does not require process-local state from a previous call, pass the same object from a terminal:

```sh
indra --root "/absolute/path/to/your/Vault" action --json '<JSON object>'
```

`indra.actions {}` lists the shared names. Use the installed `indra.instruction` and this reference for their contracts. Source-specific catalogs expose provider method schemas; they do not promise a separately discoverable schema for every fixed shared Action.

## Connection and source reads

| Action | `params` | Follow-up |
| --- | --- | --- |
| `connector.status` | `{}` | Inspect each source's actual state. |
| `connector.connect` | Required `source`; optional `requestId`, `presentation` | Follow the returned authorization job. |
| `connector.job` | `{"id":"<returned-job-id>"}` | Continue until provider verification or a terminal failure/cancellation. |
| `connector.recover` | `{}` | Open returned live `recovery.url`; keep its host alive. |
| `connector.read` | Required `source`; optional `request` | Inspect the bounded result and coverage. |
| `connector.invoke` | `source`, `method`, `input` with required `params` object | Verify the selected provider operation's result. |

Connection `presentation` accepts `open` or `return-url` for an explicitly selected manual presentation. The ordinary route is automatic. Keep a supplied request ID stable for the same connection attempt.

The shared read request accepts `limit` from 1 to 100, `query` up to 500 characters, and `since` / `until` date strings. Actual filters depend on the source. Some schemas offer `fileId` for one exact returned file identity; do not combine that selection with other filters.

Example:

```json
{"name":"connector.read","params":{"source":"gmail","request":{"limit":5}}}
```

Use `connector.invoke` only for a provider method whose actual catalog schema you inspected. If discovery returns the shared `connector.read` schema, call that Action directly.

## Collection and receipts

`connector.sync` accepts a supported `source`, optional `requestId`, and an optional actual `bindingId` where the source supports account targeting. It is not a generic operation for every connector.

```json
{"name":"connector.sync","params":{"source":"gmail","requestId":"gmail-import-1"}}
```

Inspect `complete`, errors, and stored progress. An unfinished pass retains its cursor; a later supported run can continue. `fleet.receipt` accepts `{"requestId":"<existing-request-id>"}` to read a resident job's durable receipt.

The resident owns startup fleet dispatch. `fleet.run` is unavailable through this interface. There is no universal `job.cancel`. Use the actual operation's cancellation mechanism or the **Cancel connection** control in connection help.

`connector.disconnect` currently handles the selected `chrome-history` local route; it is not a universal account-disconnect API. For source controls and provider revocation, see [Permissions](/docs/vision/settings/permissions).

## Browser Actions

Discover the `browser-use` catalog before using these installed schemas:

| Action | Required fields |
| --- | --- |
| `browser.open` | `url`; optional `sessionMode:automatic|isolated`, `allowedOrigins`, `source` |
| `browser.observe` | `sessionId` |
| `browser.click` | `sessionId`, exact current `control` |
| `browser.type` | `sessionId`, exact current `control`, and either `value` or retained `inputName` |
| `browser.scroll` | `sessionId`; no direction or pixel argument in this schema |
| `browser.close` | `sessionId` |
| `browser.run_goal` | `url`, `goal`, `expectedText`; optional limits and local inputs from its schema |

Use the returned session ID and fresh controls. `run_goal` can return an agent continuation rather than a verified result. Close the session after completion. Follow [Browser use](/docs/vision/browser-computer/browser-use) for a complete sequence.

Native computer methods belong to the `cua` source. Discover and invoke their actual schemas with `connector.invoke`; do not invent a fixed list of native method names.

## Sharing

Run preview and publication through the **same persistent MCP connection**. A one-shot CLI invocation closes its local context when it exits, so a preview ID from one `action` command cannot be published by a later separate command. Without an agent, use the [manual MCP Inspector procedure](/docs/vision/reference/mcp-setup#section-use-mcp-manually) and keep its connection open.

Sharing publishes a static copy. Current links are readable by anyone who has the link and have no expiry, recipient access control, or revocation. Select the material accordingly before publication.

### Preview inputs

Call `share.preview` with these fields in `params`:

| Field | Required? | Value |
| --- | --- | --- |
| `intent` | Yes | Nonempty description of the share, up to 2,000 UTF-8 bytes. |
| `audience` | Yes | Intended audience, up to 240 bytes. This is a label, not an access restriction. |
| `purpose` | Yes | Why the material is being shared, up to 1,000 bytes. |
| `candidateRefs` | Yes | Zero to 20 unique retained record IDs from `z_records.id`; use `[]` for a file-only or live-source-only selection. |
| `facts` | When information records are selected | One to 40 evidence decisions, described below. |
| `connectorSelections` | No | One to five bounded live-source reads to capture and verify. |
| `fileSelection` | No | One local-folder, Google Drive, or supported connector-file selection. |
| `keywords`, `excludeTerms` | No | Each accepts up to 20 nonempty strings, at most 120 bytes each. |
| `maxItems` | No | Integer from 1 to 20; default 8. Inspect the preview to see the selected output. |

Only the documented fields are accepted. Read the selected information or file before constructing its assessment.

### Evidence facts and assessment fields

For retained information, put the exact SQL record IDs in `candidateRefs`. Each fact identifies one selected record using `ref` and supplies:

| Field | Value |
| --- | --- |
| `ref` | A selected record ID, or the unique `ref` of a live-source selection below. |
| `title` | A concise title, up to 300 bytes. |
| `sourceQuote` | An exact supporting span from the selected evidence, up to 2,000 bytes. It stays local. |
| `shareText` | Exact outbound text for `include` or `redact`, up to 1,600 bytes. Omit it for `exclude`. |
| `necessity` | `required`, `supporting`, or `not-needed`. |
| `risks` | Up to eight distinct risk labels; use `[]` only when that reflects the inspected material. |
| `decision` | `include`, `redact`, or `exclude`. |
| `confidence` | `high`, `medium`, or `low`. |
| `reason` | Why this decision serves the requested share, up to 500 bytes. |

Allowed risk labels are `contact`, `credential`, `third-party-private`, `private-opinion`, `complaint`, `embarrassing`, `health`, `relationship`, `financial`, `political`, `sexual`, `internal-joke`, `draft`, `unverified`, and `other`.

The older `decision:"ask"` value is accepted for compatibility and normalized to inclusion. It does **not** pause publication or request approval. The optional legacy `question` field also does not create a confirmation step. Use an explicit current decision and inspect the preview.

For a text fact that needs redaction, put the exact permitted outbound wording in `shareText`; `sourceQuote` remains the original local evidence. Do not pass unsupported prose as a verified source quote.

### Live-source information

Use `connectorSelections` when the information comes from a supported current provider read instead of a retained record. Each entry has:

```json
{
  "ref": "<unique-local-selection-ref>",
  "source": "<installed-source-id>",
  "action": "<actual-read-action-from-its-catalog>",
  "params": {}
}
```

This is an entry template, not a complete Action call. Put it in the `connectorSelections` array inside `share.preview.params`. Replace the identifiers and fill `params` with the selected read action's fields. The action must support the connector's read-only information-capture contract; an arbitrary write action cannot be used here.

Give that entry a unique local `ref` and use the same value in its `facts` entries. It must not duplicate a retained `candidateRefs` ID or another live selection. Do not add the live `ref` to `candidateRefs`, which is reserved for actual Vault rows. For a live-only share, keep `candidateRefs: []` and supply the live selections plus their facts.

The service captures the selected read and checks the facts against it. It verifies that live information again before publishing. If the source changes or the quote does not match, inspect the current evidence and rebuild the preview. Selection parameters must be JSON, contain no credentials, and fit within 32 KiB per entry.

### Local and provider files

For a local-file-only preview:

```json
{
  "name": "share.preview",
  "params": {
    "intent": "Share the project handoff",
    "audience": "The project team",
    "purpose": "Explain the next implementation steps",
    "candidateRefs": [],
    "fileSelection": {
      "source": "computer-files",
      "folderPath": "<selected absolute folder>",
      "folderLabel": "Project handoff",
      "files": [{
        "path": "<exact selected file path>",
        "reviewBasis": "content",
        "necessity": "required",
        "risks": [],
        "decision": "include",
        "confidence": "high",
        "reason": "The inspected file contains the requested handoff."
      }]
    }
  }
}
```

Replace the placeholders with paths found through the authorized file source. Each local file must be inside `folderPath`. This example's empty risk list is an example assessment, not a default for every file.

All file entries require `reviewBasis`, `necessity`, `risks`, `decision`, `confidence`, and `reason`. Their assessment values are the same as above. `reviewBasis` is `content` when contents were inspected or `metadata-only` when only file information was inspected. File entries do not take `sourceQuote` or `shareText`.

Use the following shapes for other file sources; retain the required review fields on every file entry:

| File route | Fields in `fileSelection` | Identity on each entry in `files` |
| --- | --- | --- |
| Local files | `source:"computer-files"`, `folderPath`, `folderLabel`, `files` | `path`: actual absolute path within the selected folder. |
| Google Drive | `source:"google-drive"`, `folderLabel`, `files` | `fileId`: exact provider-returned file ID. |
| Another supported file connector | `source:"connector"`, `connector:"<installed-source-id>"`, `folderLabel`, `files` | `id`: exact provider-returned file identity. |

The provider must support file inspection and byte retrieval for this route. Do not infer file-sharing support from the source's presence in a catalog. Google Docs export as PDF, Sheets as XLSX, and Slides as PPTX; ordinary stored files keep their format.

**File decisions do not edit file contents.** In the current implementation, `decision:"redact"` on a file does not redact its bytes. If a file needs redaction, create and inspect a redacted copy first, then select that copy, or exclude the file. Text facts use the separate `shareText` mechanism.

A selection accepts up to 40 file decisions, but the published result allows at most 20 included files, 10 MiB per file, and 25 MiB total. `folderLabel` is limited to 300 bytes. Oversized or changed files require a corrected selection and new preview; do not silently drop requested files.

### Publish and inspect

The preview returns `previewId`, the assembled recommendation, and `expiresAt`. It remains valid for 30 minutes while its owning process remains alive. Inspect the recommended text, files, review status, and any removals; a preview with no publishable content cannot produce a link.

In that same MCP connection, publish the checked selection:

```json
{"name":"share.create-link","params":{"previewId":"<returned-previewId>"}}
```

The result includes `url`, item/file counts, byte count, and a hash. Inspect the published copy with `share.inspect-link` and `{"url":"<returned-url>"}`. Its `files` manifest contains each file's `id`; pass that value as `fileId` to the reader:

```json
{"name":"share.read-file","params":{"url":"<returned-url>","fileId":"<manifest-file-id>"}}
```

The reader returns supported valid UTF-8 text up to 1 MiB. Binary content and larger text files return download metadata instead. Inspecting a published URL does not depend on retaining the preview process.

Changed live-source information, expired previews, or changed file metadata require a fresh preview. See [Save and share results](/docs/vision/tools/sharing) for the complete selection and publication workflow.
