@consciousclouds/operator-shell 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +80 -31
  3. package/dist/chief/ChiefDrawer.d.ts +34 -2
  4. package/dist/chief/ChiefDrawer.d.ts.map +1 -1
  5. package/dist/chief/ChiefDrawer.js +43 -30
  6. package/dist/chief/ChiefDrawer.js.map +1 -1
  7. package/dist/chief/ChiefHeaderBar.d.ts +19 -0
  8. package/dist/chief/ChiefHeaderBar.d.ts.map +1 -0
  9. package/dist/chief/ChiefHeaderBar.js +7 -0
  10. package/dist/chief/ChiefHeaderBar.js.map +1 -0
  11. package/dist/chief/ChiefMarkdown.d.ts +12 -0
  12. package/dist/chief/ChiefMarkdown.d.ts.map +1 -0
  13. package/dist/chief/ChiefMarkdown.js +95 -0
  14. package/dist/chief/ChiefMarkdown.js.map +1 -0
  15. package/dist/chief/ChiefPanel.d.ts +44 -1
  16. package/dist/chief/ChiefPanel.d.ts.map +1 -1
  17. package/dist/chief/ChiefPanel.js +79 -29
  18. package/dist/chief/ChiefPanel.js.map +1 -1
  19. package/dist/chief/ChiefRegion.d.ts +44 -1
  20. package/dist/chief/ChiefRegion.d.ts.map +1 -1
  21. package/dist/chief/ChiefRegion.js +63 -27
  22. package/dist/chief/ChiefRegion.js.map +1 -1
  23. package/dist/chief/ChiefSession.d.ts +46 -10
  24. package/dist/chief/ChiefSession.d.ts.map +1 -1
  25. package/dist/chief/ChiefSession.js +252 -6
  26. package/dist/chief/ChiefSession.js.map +1 -1
  27. package/dist/chief/ChiefTrigger.d.ts +26 -0
  28. package/dist/chief/ChiefTrigger.d.ts.map +1 -0
  29. package/dist/chief/ChiefTrigger.js +21 -0
  30. package/dist/chief/ChiefTrigger.js.map +1 -0
  31. package/dist/chief/conversation-adapter.d.ts +70 -0
  32. package/dist/chief/conversation-adapter.d.ts.map +1 -0
  33. package/dist/chief/conversation-adapter.js +26 -0
  34. package/dist/chief/conversation-adapter.js.map +1 -0
  35. package/dist/chief/conversation-identity.d.ts +48 -0
  36. package/dist/chief/conversation-identity.d.ts.map +1 -0
  37. package/dist/chief/conversation-identity.js +100 -0
  38. package/dist/chief/conversation-identity.js.map +1 -0
  39. package/dist/chief/personality-display.d.ts +56 -0
  40. package/dist/chief/personality-display.d.ts.map +1 -0
  41. package/dist/chief/personality-display.js +52 -0
  42. package/dist/chief/personality-display.js.map +1 -0
  43. package/dist/chief/turn-adapter.d.ts +45 -0
  44. package/dist/chief/turn-adapter.d.ts.map +1 -1
  45. package/dist/chief/use-chief-turn.d.ts +127 -14
  46. package/dist/chief/use-chief-turn.d.ts.map +1 -1
  47. package/dist/chief/use-chief-turn.js +284 -28
  48. package/dist/chief/use-chief-turn.js.map +1 -1
  49. package/dist/chief/use-controlled-open.d.ts +2 -0
  50. package/dist/chief/use-controlled-open.d.ts.map +1 -0
  51. package/dist/chief/use-controlled-open.js +27 -0
  52. package/dist/chief/use-controlled-open.js.map +1 -0
  53. package/dist/chief/use-smooth-stream.d.ts +8 -0
  54. package/dist/chief/use-smooth-stream.d.ts.map +1 -0
  55. package/dist/chief/use-smooth-stream.js +128 -0
  56. package/dist/chief/use-smooth-stream.js.map +1 -0
  57. package/dist/flavor/types.d.ts +36 -21
  58. package/dist/flavor/types.d.ts.map +1 -1
  59. package/dist/frame/ComposedWorkspace.d.ts +39 -0
  60. package/dist/frame/ComposedWorkspace.d.ts.map +1 -0
  61. package/dist/frame/ComposedWorkspace.js +94 -0
  62. package/dist/frame/ComposedWorkspace.js.map +1 -0
  63. package/dist/frame/OperatorShell.d.ts +115 -13
  64. package/dist/frame/OperatorShell.d.ts.map +1 -1
  65. package/dist/frame/OperatorShell.js +200 -12
  66. package/dist/frame/OperatorShell.js.map +1 -1
  67. package/dist/guard/permissions.d.ts +2 -2
  68. package/dist/guard/permissions.js +2 -2
  69. package/dist/header/OperatorHeader.d.ts +15 -2
  70. package/dist/header/OperatorHeader.d.ts.map +1 -1
  71. package/dist/header/OperatorHeader.js +3 -3
  72. package/dist/header/OperatorHeader.js.map +1 -1
  73. package/dist/icons/registry.d.ts +7 -1
  74. package/dist/icons/registry.d.ts.map +1 -1
  75. package/dist/icons/registry.js +31 -2
  76. package/dist/icons/registry.js.map +1 -1
  77. package/dist/index.d.ts +24 -11
  78. package/dist/index.d.ts.map +1 -1
  79. package/dist/index.js +43 -17
  80. package/dist/index.js.map +1 -1
  81. package/dist/sidebar/OperatorSidebar.d.ts +16 -1
  82. package/dist/sidebar/OperatorSidebar.d.ts.map +1 -1
  83. package/dist/sidebar/OperatorSidebar.js +13 -10
  84. package/dist/sidebar/OperatorSidebar.js.map +1 -1
  85. package/dist/workspace/FormWorkspace.d.ts +2 -3
  86. package/dist/workspace/FormWorkspace.d.ts.map +1 -1
  87. package/dist/workspace/FormWorkspace.js.map +1 -1
  88. package/dist/workspace/session-adapter.d.ts +95 -0
  89. package/dist/workspace/session-adapter.d.ts.map +1 -0
  90. package/dist/workspace/session-adapter.js +29 -0
  91. package/dist/workspace/session-adapter.js.map +1 -0
  92. package/package.json +10 -5
  93. package/styles/source.css +9 -0
@@ -0,0 +1,56 @@
1
+ /**
2
+ * PersonalityDisplay — the Chief region's display-identity seam (the
3
+ * ai-factory-domain-model D-Q2 law): over time, display identity
4
+ * (displayName · icon · accent) moves from Flavor decoration into the
5
+ * Factory personality record. This type is the seam that record will feed —
6
+ * the shell renders "the current personality" and never knows which one.
7
+ *
8
+ * THE GUARDRAIL (D-Q2, verbatim): `displayName` is literal, but icon and
9
+ * accent travel as REFERENCES — an icon-registry name and a token ROLE name
10
+ * — resolved through the shell's icon registry and the Token System. Never
11
+ * a raw asset, never a raw hex value: Brand/tokens stay the single owner of
12
+ * appearance. Unknown references FAIL CLOSED to the shell defaults.
13
+ *
14
+ * Precedence for the rendered title:
15
+ * `personalityDisplay.displayName` > `flavor.chief.title` > `"Chief"`.
16
+ */
17
+ import { type LucideIcon } from "lucide-react";
18
+ import { type IconRegistry } from "../icons/registry.js";
19
+ /** What the Factory personality record will feed the Chief region (D-Q2). */
20
+ export interface PersonalityDisplay {
21
+ /** Literal display name (e.g. the personality record's displayName). */
22
+ displayName: string;
23
+ /**
24
+ * Icon by NAME, resolved through the shell's icon registry (product
25
+ * extensions apply — same seam as nav icons). Unknown ⇒ the registry's
26
+ * deterministic fallback. Never a component, never an asset URL.
27
+ */
28
+ iconRef?: string;
29
+ /**
30
+ * Accent by token ROLE name (e.g. `"primary"`), resolved through the
31
+ * Token System's CSS variables. Unknown role ⇒ undefined (the shell's
32
+ * default accent classes stand). Never a raw color value.
33
+ */
34
+ accentRef?: string;
35
+ }
36
+ /**
37
+ * The one title precedence rule, pure and provable:
38
+ * `personalityDisplay.displayName` > `flavor.chief.title` > `"Chief"`.
39
+ */
40
+ export declare function resolveChiefTitle(personalityDisplay: PersonalityDisplay | undefined, flavorTitle: string | undefined): string;
41
+ /**
42
+ * Resolve an accent ROLE reference to a composable CSS color. Only the Token
43
+ * System's declared color roles resolve (`hsl(var(--role))` — the tokens
44
+ * package's composition rule); anything else — including a raw hex value —
45
+ * fails closed to `undefined`, leaving the shell's default token classes in
46
+ * charge. References only, never values (the D-Q2 guardrail).
47
+ */
48
+ export declare function resolvePersonalityAccent(accentRef?: string): string | undefined;
49
+ /**
50
+ * Resolve the panel/trigger icon: an `iconRef` goes through the shell's icon
51
+ * registry (product extensions first, then built-ins, then the deterministic
52
+ * unknown-icon fallback — the Icon Platform's total resolution); no
53
+ * reference at all keeps the shell's default glyph.
54
+ */
55
+ export declare function resolvePersonalityIcon(personalityDisplay: PersonalityDisplay | undefined, icons?: IconRegistry, iconFamily?: string): LucideIcon;
56
+ //# sourceMappingURL=personality-display.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"personality-display.d.ts","sourceRoot":"","sources":["../../src/chief/personality-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAIzD,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEtE,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,kBAAkB,GAAG,SAAS,EAClD,WAAW,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,kBAAkB,EAAE,kBAAkB,GAAG,SAAS,EAClD,KAAK,CAAC,EAAE,YAAY,EACpB,UAAU,CAAC,EAAE,MAAM,GAClB,UAAU,CAGZ"}
@@ -0,0 +1,52 @@
1
+ /**
2
+ * PersonalityDisplay — the Chief region's display-identity seam (the
3
+ * ai-factory-domain-model D-Q2 law): over time, display identity
4
+ * (displayName · icon · accent) moves from Flavor decoration into the
5
+ * Factory personality record. This type is the seam that record will feed —
6
+ * the shell renders "the current personality" and never knows which one.
7
+ *
8
+ * THE GUARDRAIL (D-Q2, verbatim): `displayName` is literal, but icon and
9
+ * accent travel as REFERENCES — an icon-registry name and a token ROLE name
10
+ * — resolved through the shell's icon registry and the Token System. Never
11
+ * a raw asset, never a raw hex value: Brand/tokens stay the single owner of
12
+ * appearance. Unknown references FAIL CLOSED to the shell defaults.
13
+ *
14
+ * Precedence for the rendered title:
15
+ * `personalityDisplay.displayName` > `flavor.chief.title` > `"Chief"`.
16
+ */
17
+ import { Sparkles } from "lucide-react";
18
+ import { COLOR_TOKEN_ROLES } from "@consciousclouds/tokens";
19
+ import { resolveIcon } from "../icons/registry.js";
20
+ /**
21
+ * The one title precedence rule, pure and provable:
22
+ * `personalityDisplay.displayName` > `flavor.chief.title` > `"Chief"`.
23
+ */
24
+ export function resolveChiefTitle(personalityDisplay, flavorTitle) {
25
+ return personalityDisplay?.displayName ?? flavorTitle ?? "Chief";
26
+ }
27
+ /**
28
+ * Resolve an accent ROLE reference to a composable CSS color. Only the Token
29
+ * System's declared color roles resolve (`hsl(var(--role))` — the tokens
30
+ * package's composition rule); anything else — including a raw hex value —
31
+ * fails closed to `undefined`, leaving the shell's default token classes in
32
+ * charge. References only, never values (the D-Q2 guardrail).
33
+ */
34
+ export function resolvePersonalityAccent(accentRef) {
35
+ if (accentRef === undefined)
36
+ return undefined;
37
+ return COLOR_TOKEN_ROLES.includes(accentRef)
38
+ ? `hsl(var(--${accentRef}))`
39
+ : undefined;
40
+ }
41
+ /**
42
+ * Resolve the panel/trigger icon: an `iconRef` goes through the shell's icon
43
+ * registry (product extensions first, then built-ins, then the deterministic
44
+ * unknown-icon fallback — the Icon Platform's total resolution); no
45
+ * reference at all keeps the shell's default glyph.
46
+ */
47
+ export function resolvePersonalityIcon(personalityDisplay, icons, iconFamily) {
48
+ if (!personalityDisplay?.iconRef)
49
+ return Sparkles;
50
+ return resolveIcon(personalityDisplay.iconRef, icons, iconFamily);
51
+ }
52
+ //# sourceMappingURL=personality-display.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"personality-display.js","sourceRoot":"","sources":["../../src/chief/personality-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAmB,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,OAAO,EAAE,WAAW,EAAqB,MAAM,sBAAsB,CAAC;AAoBtE;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,kBAAkD,EAClD,WAA+B;IAE/B,OAAO,kBAAkB,EAAE,WAAW,IAAI,WAAW,IAAI,OAAO,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAAkB;IACzD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAQ,iBAAuC,CAAC,QAAQ,CAAC,SAAS,CAAC;QACjE,CAAC,CAAC,aAAa,SAAS,IAAI;QAC5B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,kBAAkD,EAClD,KAAoB,EACpB,UAAmB;IAEnB,IAAI,CAAC,kBAAkB,EAAE,OAAO;QAAE,OAAO,QAAQ,CAAC;IAClD,OAAO,WAAW,CAAC,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;AACpE,CAAC"}
@@ -20,6 +20,36 @@
20
20
  * wrapper are both valid adapters.
21
21
  */
22
22
  import type { ConductorEventHandler } from "@consciousclouds/conductor-sdk";
23
+ /**
24
+ * The operator's OPERATIONAL CONTEXT — what they are currently engaged with, not
25
+ * merely where they navigated. Inert and advisory: forwarded to the turn so the
26
+ * personality can respond with awareness of the operator's situation ("compare
27
+ * this with production" → it already knows what *this* is). Same rule as
28
+ * `personalityRef`: NEVER an endpoint, NEVER authority, NEVER data or secrets —
29
+ * it only says "here is what the operator is doing." A shared contract every
30
+ * product's shell fills from its own router/scope; no product-specific hack.
31
+ */
32
+ export interface TurnContext {
33
+ /**
34
+ * WHERE the operator is. Today a route/URL; tomorrow a workspace, panel,
35
+ * frame, or wall display — deliberately broader than "route".
36
+ */
37
+ location?: string;
38
+ /** The active project/product scope (e.g. `"eno"`, `"cloudchief"`). */
39
+ scope?: string;
40
+ /** The active workspace id, if any. */
41
+ workspace?: string;
42
+ /**
43
+ * WHAT the operator is engaged with — the object of their attention: a
44
+ * deployment, trace, SDK, comparison, pinned investigation, project… The
45
+ * `kind` is a product noun; the `id` opens it. This is the "operational" in
46
+ * operational context — the thing "this" refers to.
47
+ */
48
+ engagement?: {
49
+ kind: string;
50
+ id: string;
51
+ };
52
+ }
23
53
  /** What the panel hands the adapter — a prompt plus the Flavor's inert refs. */
24
54
  export interface TurnAdapterRequest {
25
55
  /** The operator's prompt. */
@@ -30,6 +60,21 @@ export interface TurnAdapterRequest {
30
60
  * the product owns what it means. Never an endpoint, never authority.
31
61
  */
32
62
  personalityRef?: string;
63
+ /**
64
+ * The operator's OPERATIONAL CONTEXT (optional, additive) — what they're
65
+ * engaged with, so the personality responds with situational awareness. Inert;
66
+ * never authority. The shell fills it; the adapter forwards it to the turn.
67
+ */
68
+ context?: TurnContext;
69
+ /**
70
+ * The conversation this turn belongs to (Session Binder slice 2a) — the
71
+ * shell's mint-or-adopt identity, forwarded VERBATIM as the wire contract's
72
+ * `conversation_id` (the inert thread-grouping key; the conductor records the
73
+ * turn's transcript under it). Never authority: every durable read is
74
+ * re-authorized server-side against the verified operator. Absent ⇒ the turn
75
+ * is recorded unattributed to any thread.
76
+ */
77
+ conversationId?: string;
33
78
  }
34
79
  /** The in-flight turn: awaitable to its end, abortable before it. */
35
80
  export interface TurnAdapterHandle {
@@ -1 +1 @@
1
- {"version":3,"file":"turn-adapter.d.ts","sourceRoot":"","sources":["../../src/chief/turn-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAAC;CAC3F"}
1
+ {"version":3,"file":"turn-adapter.d.ts","sourceRoot":"","sources":["../../src/chief/turn-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAE5E;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,gCAAgC;IAChC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CACP,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,qBAAqB,GAC7B,iBAAiB,CAAC;CACtB"}
@@ -1,23 +1,48 @@
1
1
  /**
2
2
  * useChiefTurn — the Chief turn flow, extracted from the rail panel so every
3
- * PLACEMENT of the AI Region (rail, drawer) runs the IDENTICAL behavior:
4
- * turn lifecycle over the injected TurnAdapter (P1-1 — the product owns the
5
- * wire), the conductor-sdk event vocabulary (`delta` / `routed` / `error`),
6
- * the reference outcome precedence (routed > error > streamed text), and the
7
- * in-console routed-directive guard DERIVED from the Flavor's nav. Placement
8
- * moves the panel; it never touches this hook.
3
+ * PLACEMENT of the AI Region (rail, push, overlay) runs the IDENTICAL
4
+ * behavior: turn lifecycle over the injected TurnAdapter (P1-1 — the product
5
+ * owns the wire), the conductor-sdk event vocabulary (`delta` / `routed` /
6
+ * `error`), the reference outcome precedence (routed > error > streamed
7
+ * text), and the in-console routed-directive guard DERIVED from the Flavor's
8
+ * nav. Placement moves the panel; it never touches this hook.
9
+ *
10
+ * `submitPrompt` is the one entry to a turn — the composer's form submit and
11
+ * the empty-state suggestion chips both call it, so a suggestion is a canned
12
+ * question, never a second code path.
9
13
  */
10
14
  import * as React from "react";
15
+ import type { CanvasDefinition } from "@consciousclouds/canvas-sdk";
11
16
  import type { OperatorFlavor } from "../flavor/types.js";
12
- import type { TurnAdapter } from "./turn-adapter.js";
17
+ import type { ConversationAdapter, ConversationThreadSummary } from "./conversation-adapter.js";
18
+ import { type PersonalityDisplay } from "./personality-display.js";
19
+ import type { TurnAdapter, TurnContext } from "./turn-adapter.js";
13
20
  /** Post-turn status line: routed (0 tokens) · off-console · transport error. */
14
21
  export interface ChiefTurnMeta {
15
22
  kind: "routed" | "unavailable" | "error";
16
23
  text: string;
17
24
  }
18
- /** Everything a Chief presentation (rail aside, drawer sheet) renders from. */
25
+ /**
26
+ * One exchange of the visible thread: the operator's question and the answer
27
+ * as it streamed. `key` is a client render key; `turnId` is the CANONICAL
28
+ * conductor turn id (from the stream's `started` event) — the same id the
29
+ * durable transcript records, so a rendered turn and its Memory turn group
30
+ * share one name.
31
+ */
32
+ export interface ChiefTurnEntry {
33
+ key: string;
34
+ turnId?: string;
35
+ question: string;
36
+ answer: string;
37
+ meta: ChiefTurnMeta | null;
38
+ }
39
+ /** Everything a Chief presentation (rail, push panel, overlay) renders from. */
19
40
  export interface ChiefTurnSession {
20
- /** Panel display title (Flavor-decorated; defaults to `Chief`). */
41
+ /**
42
+ * Panel display title. Precedence: `personalityDisplay.displayName` (the
43
+ * Factory personality-record seam, D-Q2) > `flavor.chief.title` (Flavor
44
+ * decoration) > `Chief`.
45
+ */
21
46
  title: string;
22
47
  /** Input placeholder (defaults to `Ask {title}…`). */
23
48
  placeholder: string;
@@ -25,26 +50,114 @@ export interface ChiefTurnSession {
25
50
  hint: string;
26
51
  /** Optional emphasized example question rendered after the hint. */
27
52
  hintExample?: string;
53
+ /** Empty-state suggestion chips (inert Flavor strings; may be empty). */
54
+ suggestions: readonly string[];
28
55
  /** The composer's current input value. */
29
56
  cmd: string;
30
57
  setCmd: (value: string) => void;
31
58
  /** A turn is in flight. */
32
59
  busy: boolean;
33
- /** The last submitted question (null before the first turn). */
60
+ /**
61
+ * The visible THREAD (Session Binder slice 2b): every exchange of this
62
+ * conversation since it became visible, oldest first. Speaking appends —
63
+ * it never erases the prior exchange. The LAST entry is the live one while
64
+ * `busy` (its `answer` is still streaming).
65
+ */
66
+ turns: readonly ChiefTurnEntry[];
67
+ /** The current (last) turn's question (null before the first turn). */
34
68
  question: string | null;
35
- /** The streamed answer so far. */
69
+ /** The current (last) turn's streamed answer so far. */
36
70
  answer: string;
37
- /** Post-turn status (routed / off-console / error), if any. */
71
+ /** The current (last) turn's post-turn status (routed / off-console / error). */
38
72
  meta: ChiefTurnMeta | null;
39
73
  /** A turn has been asked — render the thread instead of the idle hint. */
40
74
  showThread: boolean;
41
- /** Composer submit handler (form onSubmit). */
75
+ /** Composer submit handler (form onSubmit) — submits the composer value. */
42
76
  submit: (e: React.FormEvent) => Promise<void>;
77
+ /** Submit an arbitrary prompt (suggestion chips) — the SAME turn flow. */
78
+ submitPrompt: (prompt: string) => Promise<void>;
79
+ /**
80
+ * A ConversationAdapter is injected — the durable transcript surface exists
81
+ * (the Conversations tab renders, threads hydrate). False ⇒ live-only.
82
+ */
83
+ transcriptEnabled: boolean;
84
+ /**
85
+ * The operator's durable conversation THREADS (the Conversations tab),
86
+ * most-recently-active first. Empty without a ConversationAdapter.
87
+ */
88
+ conversations: readonly ConversationThreadSummary[];
89
+ /** The ACTIVE conversation id (the thread the composer speaks into). */
90
+ activeConversationId: string;
91
+ /** Rejoin an existing thread (adopt its id; the visible thread re-hydrates). */
92
+ openConversation: (conversationId: string) => void;
93
+ /** Start a fresh thread (mint + adopt; the visible thread clears). */
94
+ newConversation: () => void;
43
95
  }
44
96
  export interface UseChiefTurnOptions {
45
97
  flavor: OperatorFlavor;
46
98
  /** The product's transport (P1-1). The shell owns the panel, never the wire. */
47
99
  adapter: TurnAdapter;
100
+ /**
101
+ * Display identity from the Factory personality record (D-Q2 seam) —
102
+ * `displayName` beats `flavor.chief.title`. Optional: without it the
103
+ * Flavor's decoration (then `Chief`) stands.
104
+ */
105
+ personalityDisplay?: PersonalityDisplay;
106
+ /**
107
+ * The product's OPERATIONAL CONTEXT beyond location (`scope` / `workspace` /
108
+ * `engagement`) — inert, advisory, forwarded on every turn. The shell always
109
+ * fills `location` itself (from the router); a product that also knows its
110
+ * scope or what the operator is engaged with supplies it here. Omitted ⇒ the
111
+ * turn carries location alone. Never authority (same rule as `personalityRef`).
112
+ */
113
+ context?: Omit<TurnContext, "location">;
114
+ /**
115
+ * The compose→center seam (M2 precondition 1): called when a turn produces a
116
+ * transient CanvasDefinition (a tool's `tool_done.result` parsed as
117
+ * `canvas-definition` by the ONE ai-client parser). The shell owns the panel;
118
+ * the SHELL — not the product page — lifts the composed workspace to the center
119
+ * (OperatorShell drives WorkspaceHost). Inert until a compose tool actually
120
+ * emits one; a turn that composes nothing never calls this. `meta` carries the
121
+ * composition's PROVENANCE (composer/intent/conversation) — the source state the
122
+ * Keep-composition gesture persists; never render output.
123
+ */
124
+ onComposed?: (canvas: CanvasDefinition, meta: ComposedMeta) => void;
125
+ /**
126
+ * Composition ACTIVITY (real runtime events, never simulated): fired 'composing'
127
+ * when a compose-class tool STARTS (tool name convention: `compose*` — the same
128
+ * vocabulary the conductor's composer tools use), and 'idle' when the turn ends
129
+ * WITHOUT a composed canvas (failure/no-op — the center falls back). A successful
130
+ * composition ends with onComposed instead. Drives the shell's composing animation
131
+ * — motion as continuity, anchored to actual execution.
132
+ */
133
+ onComposeActivity?: (phase: "composing" | "idle") => void;
134
+ /**
135
+ * The conversation TRANSCRIPT transport (the read dual of `adapter`, Session
136
+ * Binder consumption slice): lets the hook HYDRATE the visible thread from
137
+ * the durable transcript (mount + adoption) and feed the drawer's
138
+ * Conversations tab. Optional and fail-closed: without it there is no tab,
139
+ * no hydration — the live turn flow stands alone.
140
+ */
141
+ conversationAdapter?: ConversationAdapter;
142
+ }
143
+ /**
144
+ * Provenance of a composed canvas, delivered alongside it by the binder: WHO
145
+ * composed it (the tool), WHAT its intent key is (the emitter's correlationId),
146
+ * and WHICH conversation owns it (the shell-minted session correlation id —
147
+ * "a conversation owns a workspace", Canvas OS §4).
148
+ */
149
+ export interface ComposedMeta {
150
+ composer: string;
151
+ intent: string;
152
+ conversationId: string;
153
+ /**
154
+ * The CANONICAL conductor turn id (from the stream's `started` event — minted by
155
+ * RunTurn, never fabricated client-side). The workspace ANCHOR: a kept composition
156
+ * is anchored to the turn that composed it, so reopening it can restore the
157
+ * conversation to that exact moment once the durable transcript exists (the
158
+ * Session Binder). Absent only if the stream never emitted `started`.
159
+ */
160
+ turnId?: string;
48
161
  }
49
- export declare function useChiefTurn({ flavor, adapter }: UseChiefTurnOptions): ChiefTurnSession;
162
+ export declare function useChiefTurn({ flavor, adapter, personalityDisplay, context: providedContext, onComposed, onComposeActivity, conversationAdapter, }: UseChiefTurnOptions): ChiefTurnSession;
50
163
  //# sourceMappingURL=use-chief-turn.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"use-chief-turn.d.ts","sourceRoot":"","sources":["../../src/chief/use-chief-turn.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAM/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,aAAa,GAAG,OAAO,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,2BAA2B;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,gEAAgE;IAChE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,gFAAgF;IAChF,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,mBAAmB,GAAG,gBAAgB,CAwFvF"}
1
+ {"version":3,"file":"use-chief-turn.d.ts","sourceRoot":"","sources":["../../src/chief/use-chief-turn.ts"],"names":[],"mappings":"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"}