# Factory Droid

> Import local Factory Droid sessions, and Factory cloud sessions on request.

Local Droid sessions provide Hansard's most complete Factory import.
Factory enables the cloud Sessions API only for selected organizations.

## Source IDs

| Source          | Use it for                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `factory`       | Local Droid JSONL transcripts in `~/.factory/sessions` and their settings and usage files.                                           |
| `factory-cloud` | Factory cloud sessions, read from the Sessions API. Runs when you ask for it or turn it on in **Settings → Imports → Cloud agents**. |

## How the import works

The local source reads each Droid JSONL transcript with its matching settings
and usage files. It rebuilds user and assistant messages, reasoning, tool calls
and results, file changes, model and usage data, and worker sessions in the
order Factory recorded them. Each worker session becomes its own conversation
linked to its parent, instead of being folded into the parent where you cannot
see it.

The cloud source reads Factory's Sessions API. When a cloud session matches a
local session Hansard already imported, Hansard keeps the richer local
transcript and adds the cloud details to it. The cloud normalizer imports chat
and tool output. It does not currently normalize tool arguments or diffs.
Hansard preserves the returned response bodies as raw evidence.
Importing again updates the same sessions.
Whether you can read cloud sessions depends on your organization's API access.

Cloud-only archives continue fetching cloud messages when the session changes.
`--since all` and `--session` also reread messages when the provider clock has
not changed. Unchanged captures leave the archive untouched. Stale, failed,
truncated, or thinner captures keep retained history and remain retryable.

## Import and keep current

**Import now**

```sh
hansard import --source factory --since all
hansard import factory-cloud --since all
hansard index rebuild
```

The cloud import uses `FACTORY_API_KEY` or `factory.apiKey` in Hansard's
config. It only reads from Factory, and Hansard never stores the key in the
archive.

**Keep current**

With **Automatic** source selection, the watcher already includes `factory`.
With a **Custom** list, enable it. The watcher picks it up within 30 seconds:

```sh
hansard config sources enable factory
```

To keep cloud sessions current, turn on **Factory cloud sessions** in
**Settings → Imports → Cloud agents**. The watcher then refreshes it every six
hours. Otherwise, run the command again when you want newer cloud sessions.

## Review the import in the app

1. When the import finishes, open **Conversations** and select **Filter & sort**.
2. Set **Source** to **Factory Droid or Factory cloud sessions** and set **Time** to the window you imported. Use **Folder** to narrow the list when you use this harness in several projects.
3. Select a conversation to check its messages, tool calls, files, commits, model, and token usage.

To keep archiving new sessions from a local harness, open **Settings → Imports**. **Automatic** follows every supported harness installed on this computer. **Custom** lets you turn individual harnesses on or off. Cloud sources and account exports never run from here; each needs its own import command. If a conversation you expect is missing after you reset the filters, run the import command on this page again with `--explain-skips` where the source supports it.

## What Hansard preserves

- Local messages, tool calls, diffs, linked worker sessions, and usage totals.
- Cloud chat, status, repository, and the tool output the Sessions API returns.
- The local transcript when the same cloud work also has a local Droid copy.
- Local reply model IDs and reasoning effort when the transcript records them.
  Current session settings remain separate from historical reply attribution.
  Model-only context is preserved without counting as a human prompt.
- Recorded reply effort counts, including replies whose effort is not recorded.
  Session token totals have no measured split by reply or effort; Stats uses
  reply counts when distributing tokens across recorded effort levels.
- Explicit zero usage and credit counters, kept separate from absent values.
- Embedded image and document bytes from messages and tool results, stored as
  attachment sidecars. Successful Create and Edit calls supply file-change
  counts; failed edits contribute no changed lines.

## Known limitations

- Factory offers the Sessions API only to selected organizations. Without
  access, the cloud import reports that your organization is not enabled,
  rather than an authentication error.
- Cloud-only sessions can show results without matching tool calls. The public
  Sessions API documentation does not specify the message response schema.
  Current native tool-argument availability needs an authenticated account
  trial. An earlier limited response does not establish permanent API absence.
- A cloud session that names no repository has no project, because its hosted
  working directory is not a folder on your machine.
- Cloud session model settings remain separate from the models recorded on
  individual messages. Missing historical model attribution stays unknown.
- Local turn outcomes, source host and format metadata, tags, policy
  settings, and last-call or child-inclusive usage remain available in raw
  files. They do not supply additional session usage or inferred message links.
- An attachment URL or local path without embedded bytes stays unavailable.
  Import does not fetch the URL or reopen the referenced local file.

## Refresh an existing archive

```sh
hansard import --source factory --since all
hansard import factory-cloud --since all
hansard index rebuild
```