# LoomSession

One agent's time with a loom in one interaction run: what it woke up knowing, what it was shown, what it recalled and wove. Night weaving reads it to judge what mattered and what went unused.

**Kind:** an object, used in responses.

## Fields

Every field is present in a response; empty ones are `null`.

| Field | Type | Description |
|---|---|---|
| `loomId` | `uuid` | The loom. |
| `interactionProcessId` | `uuid` | The interaction run the session belongs to. |
| `agentName` | `string` | The agent's name in the interaction. |
| `agentId` | `uuid \| null` | The agent's id, when known. |
| `tapestry` | `string \| null` | What the agent woke up knowing ("What You Know"): woven once, on its first turn, then fixed for the rest of the session. |
| `tapestryWovenAt` | `datetime \| null` | When the tapestry was woven (UTC). Null until the agent's first turn. |
| `subjects` | `string[]` | The people and things present when the tapestry was woven: whoever sent messages, and the values of the interaction's subject inputs. |
| `tapestryThreadIds` | `uuid[]` | The threads the tapestry was woven from. |
| `suggestedThreadIds` | `uuid[]` | Threads offered to the agent during the conversation because something said touched them. |
| `heldBackThreadIds` | `uuid[]` | Threads the loom found for this agent this session but held back after vetting them, so the agent never saw them: a cue said in another sense, a guess that did not belong, a recall result that did not answer. They can come up again, and night weaving never counts them as unused. |
| `cuedThreadIds` | `uuid[]` | Threads brought back this session because someone said one of their cues. A cue brings a thread back once a session; these are also in `suggestedThreadIds`, so night weaving judges them like any suggestion. |
| `heldThreadIds` | `uuid[]` | Threads the agent pinned (held close) during this session. The tapestry it woke with already carries what was pinned before; these are put back when the conversation is summarised, so the agent keeps them. |
| `pendingGiftThreadIds` | `uuid[]` | Threads another agent in this conversation gave this one, waiting to be offered on its next turn. |
| `recalledThreadIds` | `uuid[]` | Threads the agent recalled (by searching or reflecting): evidence they were used. |
| `wovenThreadIds` | `uuid[]` | Threads woven, reframed, pinned or cut during this session. |
| `seenThreadIds` | `uuid[]` | Threads only shown to the agent (when it inspected the loom, or as knots and tensions in a reflection): known, not used. |
| `pendingProposals` | [`ProposedThread`](https://docs.maitento.com/reference/types/proposed-thread.md)`[]` | Threads the loom proposes the agent weave, waiting to be offered on its next turn. Used when the interaction's loom weaves in `Suggest` mode. |
| `lastTurnAt` | `datetime \| null` | When the agent last took a turn in this session (UTC). |
| `lastSequence` | `integer` | The furthest point in the conversation (its message sequence) an agent turn in this session has reached. |
| `awaitingNight` | `boolean` | True while the session holds turns night weaving has not yet consolidated. A long conversation is consolidated night after night, each night reading only what happened after `consolidatedUpToSequence`. |
| `consolidatedUpToSequence` | `integer` | Night weaving has woven the conversation into episodes up to this message sequence. |
| `judgedThreadIds` | `uuid[]` | Threads night weaving has already judged as used or unused for this session; each is judged only once. |
| `consolidatedByNightWeavingId` | `uuid \| null` | The night weaving that most recently consolidated this session. |
| `knownThreadIds` | `uuid[]` | Every thread this agent has been shown or has touched this session: the ids it may refer back to. Set by Maitento. |
| `tenantId` | `uuid` | The id of the tenant it belongs to. |
| `id` | `uuid` | The unique id. Use it in `by-id` routes and wherever another object refers to this one. |
| `dateCreated` | `datetime` | When it was created, in UTC. |
| `dateUpdated` | `datetime` | When it was last changed, in UTC. |

## Example

```json
{
  "loomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "interactionProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "agentName": "...",
  "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "tapestry": "...",
  "tapestryWovenAt": "2026-10-26T12:00:00.0000000Z",
  "subjects": [
    "..."
  ],
  "tapestryThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "suggestedThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "heldBackThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "cuedThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "heldThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "pendingGiftThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "recalledThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "wovenThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "seenThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "pendingProposals": [
    {
      "content": "...",
      "kind": "Semantic",
      "weight": 0,
      "subjects": [],
      "tags": [],
      "cues": [],
      "until": "2026-10-26T12:00:00.0000000Z",
      "basis": "Said"
    }
  ],
  "lastTurnAt": "2026-10-26T12:00:00.0000000Z",
  "lastSequence": 0,
  "awaitingNight": false,
  "consolidatedUpToSequence": 0,
  "judgedThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "consolidatedByNightWeavingId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "knownThreadIds": [
    "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f"
  ],
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}
```

## Where it's used

- [`looms.sessions`](https://docs.maitento.com/reference/api/looms.md) (`GET /looms/by-id/{id}/sessions`)