@shardworks/parlour-apparatus 0.1.101

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Sean Boots
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# `@shardworks/parlour-apparatus`
+
+The Parlour manages multi-turn conversations within the guild. It provides the structure for two kinds of interaction: **consult** (a human talks to an anima) and **convene** (multiple animas hold a structured dialogue). The Parlour orchestrates turns — deciding *when* and *for whom* to call The Animator — while delegating session launch to The Animator and context composition to The Loom.
+
+The Parlour sits downstream of both The Animator and The Loom in the dependency graph: `stacks <- animator <- parlour` and `loom <- parlour`.
+
+---
+
+## Installation
+
+Add to your package's dependencies:
+
+```json
+{
+  "@shardworks/parlour-apparatus": "workspace:*"
+}
+```
+
+The Parlour requires The Stacks, The Animator, and The Loom to be installed in the guild.
+
+---
+
+## API
+
+The Parlour exposes a `ParlourApi` via its `provides` interface, retrieved at runtime:
+
+```typescript
+import type { ParlourApi } from '@shardworks/parlour-apparatus';
+
+const parlour = guild().apparatus<ParlourApi>('parlour');
+```
+
+### `create(request): Promise<CreateConversationResult>`
+
+Create a new conversation. Sets up the conversation and participant records but does NOT take a first turn.
+
+```typescript
+const { conversationId, participants } = await parlour.create({
+  kind: 'consult',
+  topic: 'Help me refactor the session layer',
+  turnLimit: 10,
+  cwd: '/workspace/shardworks',
+  participants: [
+    { kind: 'human', name: 'Sean' },
+    { kind: 'anima', name: 'Artificer' },
+  ],
+});
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `kind` | `'consult' \| 'convene'` | Conversation kind |
+| `topic` | `string` | Seed topic / initial prompt (optional) |
+| `turnLimit` | `number` | Max anima turns before auto-conclude (optional) |
+| `cwd` | `string` | Working directory — persists for the conversation's lifetime |
+| `participants` | `ParticipantDeclaration[]` | Who is in the conversation |
+| `eventId` | `string` | Triggering event id (optional, for clockworks) |
+
+### `takeTurn(request): Promise<TurnResult>`
+
+Take a turn in a conversation. For anima participants, weaves context and calls The Animator. For human participants, records the message as context for the next anima turn.
+
+```typescript
+// Human turn — records message, no session launched
+await parlour.takeTurn({
+  conversationId,
+  participantId: humanId,
+  message: 'What about the error handling?',
+});
+
+// Anima turn — launches a session via The Animator
+const result = await parlour.takeTurn({
+  conversationId,
+  participantId: animaId,
+  message: 'What about the error handling?', // or omit to use topic
+});
+// result.sessionResult contains the Animator's SessionResult
+// result.turnNumber is the 1-indexed turn count
+// result.conversationActive indicates if the conversation is still open
+```
+
+### `takeTurnStreaming(request): { chunks, result }`
+
+Same as `takeTurn()`, but streams output chunks as the session produces them. Returns synchronously with `{ chunks, result }` — same pattern as The Animator.
+
+```typescript
+const { chunks, result } = parlour.takeTurnStreaming({
+  conversationId,
+  participantId: animaId,
+});
+
+for await (const chunk of chunks) {
+  if (chunk.type === 'text') process.stdout.write(chunk.text);
+  if (chunk.type === 'turn_complete') console.log(`\nTurn ${chunk.turnNumber} done`);
+}
+
+const turnResult = await result;
+```
+
+Chunk types include all `SessionChunk` types from The Animator, plus:
+- `{ type: 'turn_complete', turnNumber, costUsd? }` — emitted after the session completes
+
+### `nextParticipant(conversationId): Promise<Participant | null>`
+
+Get the next participant in line. For consult: always returns the anima. For convene: round-robin by insertion order. Returns `null` if the conversation is ended or the turn limit is reached.
+
+### `end(conversationId, reason?): Promise<void>`
+
+End a conversation. Reason defaults to `'concluded'`. Idempotent — safe to call on already-ended conversations.
+
+### `list(options?): Promise<ConversationSummary[]>`
+
+List conversations with optional filters by `status`, `kind`, and `limit`. Returns summaries ordered by `createdAt` descending.
+
+### `show(conversationId): Promise<ConversationDetail | null>`
+
+Show full detail for a conversation including all turns, participant list, and aggregate cost.
+
+---
+
+## Configuration
+
+No guild-level configuration is required. The Parlour reads its dependencies from the guild's apparatus registry at startup.
+
+---
+
+## Support Kit
+
+The Parlour contributes two books and three tools to the guild:
+
+### Books
+
+| Book | Indexes | Contents |
+|---|---|---|
+| `conversations` | `status`, `kind`, `createdAt` | Conversation documents with nested participant records |
+| `turns` | `conversationId`, `turnNumber`, `participantId`, `participantKind` | Per-turn records linking conversations to Animator sessions |
+
+### Tools
+
+| Tool | Permission | Description |
+|---|---|---|
+| `conversation-list` | `read` | List conversations with optional status/kind filters |
+| `conversation-show` | `read` | Show full conversation detail including all turns |
+| `conversation-end` | `write` | End an active conversation (concluded or abandoned) |
+
+---
+
+## Key Types
+
+```typescript
+interface CreateConversationRequest {
+  kind: 'consult' | 'convene';
+  topic?: string;
+  turnLimit?: number;
+  participants: ParticipantDeclaration[];
+  cwd: string;
+  eventId?: string;
+}
+
+interface ParticipantDeclaration {
+  kind: 'anima' | 'human';
+  name: string;
+}
+
+interface TurnResult {
+  sessionResult: SessionResult | null;  // null for human turns
+  turnNumber: number;
+  conversationActive: boolean;
+}
+
+interface ConversationSummary {
+  id: string;
+  status: 'active' | 'concluded' | 'abandoned';
+  kind: 'consult' | 'convene';
+  topic: string | null;
+  participants: Participant[];
+  turnCount: number;
+  totalCostUsd: number;
+  // ... timestamps, turnLimit
+}
+```
+
+See `src/types.ts` for the complete type definitions.
+
+---
+
+## Exports
+
+The package exports all public types and the `createParlour()` factory:
+
+```typescript
+import parlourPlugin, { createParlour, type ParlourApi } from '@shardworks/parlour-apparatus';
+```
+
+The default export is a pre-built plugin instance, ready for guild installation.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @shardworks/parlour-apparatus — The Parlour.
+ *
+ * Multi-turn conversation management: creates conversations, registers
+ * participants, orchestrates turns (with streaming), enforces turn limits,
+ * and ends conversations. Delegates session launch to The Animator and
+ * context composition to The Loom.
+ *
+ * See: docs/architecture/apparatus/parlour.md
+ */
+export { type ParlourApi, type ConversationDoc, type TurnDoc, type ParticipantRecord, type Participant, type CreateConversationRequest, type CreateConversationResult, type ParticipantDeclaration, type TakeTurnRequest, type TurnResult, type ConversationChunk, type ConversationSummary, type ConversationDetail, type TurnSummary, type ListConversationsOptions, } from './types.ts';
+export { createParlour } from './parlour.ts';
+declare const _default: import("@shardworks/nexus-core").Plugin;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,wBAAwB,GAC9B,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;;AAI7C,wBAA+B"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * @shardworks/parlour-apparatus — The Parlour.
+ *
+ * Multi-turn conversation management: creates conversations, registers
+ * participants, orchestrates turns (with streaming), enforces turn limits,
+ * and ends conversations. Delegates session launch to The Animator and
+ * context composition to The Loom.
+ *
+ * See: docs/architecture/apparatus/parlour.md
+ */
+import { createParlour } from "./parlour.js";
+// ── Parlour API ─────────────────────────────────────────────────────
+export {} from "./types.js";
+export { createParlour } from "./parlour.js";
+// ── Default export: the apparatus plugin ──────────────────────────────
+export default createParlour();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,uEAAuE;AAEvE,OAAO,EAgBN,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,yEAAyE;AAEzE,eAAe,aAAa,EAAE,CAAC"}

package/dist/parlour.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The Parlour — multi-turn conversation management apparatus.
+ *
+ * Manages two kinds of conversation:
+ * - consult: a human talks to an anima
+ * - convene: multiple animas hold a structured dialogue
+ *
+ * The Parlour orchestrates turns — it decides when and for whom to call
+ * The Animator, and tracks conversation state in The Stacks. It does not
+ * launch sessions itself (delegates to The Animator) or assemble prompts
+ * (delegates to The Loom).
+ *
+ * See: docs/architecture/apparatus/parlour.md
+ */
+import type { Plugin } from '@shardworks/nexus-core';
+/**
+ * Create the Parlour apparatus plugin.
+ *
+ * Returns a Plugin with:
+ * - `requires: ['stacks', 'animator', 'loom']` — conversation orchestration
+ * - `provides: ParlourApi` — the conversation management API
+ * - `supportKit` — contributes `conversations` + `turns` books + management tools
+ */
+export declare function createParlour(): Plugin;
+//# sourceMappingURL=parlour.d.ts.map

package/dist/parlour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parlour.d.ts","sourceRoot":"","sources":["../src/parlour.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,wBAAwB,CAAC;AAiMrE;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CA+etC"}