@personaai/react 0.11.0 → 0.15.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.
package/dist/index.d.cts CHANGED
@@ -477,15 +477,31 @@ interface UseVoiceResult {
477
477
  */
478
478
  updateContext: (context: Record<string, unknown>) => void;
479
479
  }
480
- type PersonaWorkflowNodeType = "trigger" | "agent" | "tool" | "condition" | "parallel" | "code" | "human_review" | (string & {});
480
+ type PersonaWorkflowNodeType = "trigger" | "agentStep" | "knowledgeStep" | "toolStep" | "condition" | "approval" | "parallel" | "join" | "output";
481
+ type PersonaWorkflowTriggerType = "manual" | "api" | "webhook" | "schedule" | "chat";
482
+ type PersonaWorkflowVisibility = "private" | "unlisted" | "public";
483
+ type PersonaWorkflowOwnerType = "Project" | "ExternalUser";
484
+ type PersonaNodeOnErrorAction = "fail" | "continue" | "routeError";
485
+ interface PersonaNodeRetryPolicy {
486
+ maxRetries?: number;
487
+ backoffMs?: number;
488
+ exponential?: boolean;
489
+ }
490
+ interface PersonaWorkflowNodeData {
491
+ label: string;
492
+ description?: string;
493
+ config?: Record<string, unknown>;
494
+ retryPolicy?: PersonaNodeRetryPolicy;
495
+ onError?: PersonaNodeOnErrorAction;
496
+ }
481
497
  interface PersonaWorkflowNode {
482
498
  id: string;
483
499
  type: PersonaWorkflowNodeType;
484
- position: {
500
+ position?: {
485
501
  x: number;
486
502
  y: number;
487
503
  };
488
- data: Record<string, unknown>;
504
+ data: PersonaWorkflowNodeData;
489
505
  }
490
506
  interface PersonaWorkflowEdge {
491
507
  id: string;
@@ -493,55 +509,110 @@ interface PersonaWorkflowEdge {
493
509
  target: string;
494
510
  sourceHandle?: string;
495
511
  targetHandle?: string;
496
- label?: string;
512
+ condition?: unknown;
513
+ conditionValue?: string;
497
514
  }
498
515
  interface PersonaWorkflowTrigger {
499
- type: "manual" | "webhook" | "schedule" | "event" | (string & {});
516
+ type: PersonaWorkflowTriggerType;
500
517
  config?: Record<string, unknown>;
501
518
  }
502
519
  interface PersonaWorkflowDraft {
503
520
  nodes: PersonaWorkflowNode[];
504
521
  edges: PersonaWorkflowEdge[];
505
- triggers?: PersonaWorkflowTrigger[];
506
- settings?: Record<string, unknown>;
522
+ /** Singular — a draft has at most one trigger, not an array of them. */
523
+ trigger?: PersonaWorkflowTrigger;
507
524
  }
508
- interface PersonaWorkflowSummary {
525
+ interface PersonaWorkflow {
509
526
  _id: string;
527
+ domain?: string;
528
+ projectId?: string;
510
529
  name: string;
511
- slug?: string;
512
530
  description?: string;
513
- status: "draft" | "published" | "archived";
514
- visibility?: "private" | "public";
515
- activeVersion?: number;
516
- tags?: string[];
531
+ isEnabled: boolean;
532
+ visibility: PersonaWorkflowVisibility;
533
+ ownerType: PersonaWorkflowOwnerType;
534
+ externalOwnerId?: string | null;
535
+ draft: PersonaWorkflowDraft;
536
+ /** `0` until `publish()` has been called at least once. */
537
+ publishedVersion: number;
538
+ activeRuns: number;
517
539
  createdAt: string;
518
540
  updatedAt: string;
519
541
  }
520
- interface PersonaWorkflow extends PersonaWorkflowSummary {
521
- draft: PersonaWorkflowDraft;
522
- triggers?: PersonaWorkflowTrigger[];
523
- ownerId?: string;
524
- projectId?: string;
542
+ interface PersonaAgentSnapshot {
543
+ modelName: string;
544
+ systemPrompt: string;
545
+ tools?: string[];
525
546
  }
526
- interface PersonaWorkflowVersionSummary {
547
+ /** A published, immutable snapshot of a workflow's draft — what `stream()` actually executes. */
548
+ interface PersonaWorkflowVersion {
527
549
  _id: string;
528
550
  workflowId: string;
551
+ projectId: string;
529
552
  version: number;
530
- summary?: string;
553
+ definition: PersonaWorkflowDraft;
554
+ agentSnapshots?: Record<string, PersonaAgentSnapshot>;
555
+ publishedBy?: string;
556
+ publishedAt: string;
531
557
  createdAt: string;
558
+ updatedAt: string;
532
559
  }
533
- interface PersonaWorkflowRunSummary {
560
+ type PersonaWorkflowRunStatus = "queued" | "running" | "paused" | "completed" | "failed" | "cancelled";
561
+ type PersonaNodeRunStatus = "running" | "completed" | "failed" | "skipped" | "paused";
562
+ /** One node's persisted run record, as returned by the REST API after the fact — distinct from `PersonaNodeRunState` below, which is the *live*, client-derived state `useWorkflowStream` builds up from AG-UI events while a run is still in progress. */
563
+ interface PersonaNodeRun {
564
+ nodeId: string;
565
+ nodeType: string;
566
+ status: PersonaNodeRunStatus;
567
+ input?: unknown;
568
+ output?: unknown;
569
+ error?: string;
570
+ retriesTaken: number;
571
+ durationMs: number;
572
+ tokens: number;
573
+ startedAt: string;
574
+ endedAt?: string;
575
+ }
576
+ interface PersonaWorkflowUsage {
577
+ totalTokens: number;
578
+ agentTurns: number;
579
+ toolCalls: number;
580
+ creditsDeducted: number;
581
+ }
582
+ interface PersonaWorkflowRun {
534
583
  _id: string;
535
584
  workflowId: string;
536
- version: number;
537
- status: "pending" | "running" | "completed" | "failed" | "cancelled";
538
- startedAt?: string;
539
- finishedAt?: string;
540
- durationMs?: number;
541
- error?: string;
542
- isDryRun?: boolean;
585
+ workflowVersion: number;
586
+ projectId: string;
587
+ triggeredBy: {
588
+ type: PersonaWorkflowTriggerType;
589
+ userId?: string;
590
+ details?: unknown;
591
+ };
592
+ status: PersonaWorkflowRunStatus;
593
+ isDryRun: boolean;
594
+ nodeRuns: PersonaNodeRun[];
595
+ pendingApproval?: {
596
+ nodeId?: string;
597
+ prompt?: string;
598
+ options?: string[];
599
+ requestedAt?: string;
600
+ };
601
+ output?: unknown;
602
+ usage?: PersonaWorkflowUsage;
603
+ threadId: string;
604
+ startedAt: string;
605
+ endedAt?: string;
543
606
  createdAt: string;
607
+ updatedAt: string;
544
608
  }
609
+ /**
610
+ * Live, client-derived state for one node during an in-progress
611
+ * `useWorkflowStream` run — built up from `workflow_node_started`/
612
+ * `_completed`/`_failed` AG-UI events, not fetched from the REST API. See
613
+ * `PersonaNodeRun` for the persisted record `useWorkflowRuns`/`getRun`
614
+ * return once a run has actually finished.
615
+ */
545
616
  interface PersonaNodeRunState {
546
617
  nodeId: string;
547
618
  nodeType: string;
@@ -553,22 +624,31 @@ interface PersonaNodeRunState {
553
624
  output?: unknown;
554
625
  error?: string;
555
626
  }
556
- interface CreateWorkflowInput {
627
+ interface CreatePersonaWorkflowInput {
557
628
  name: string;
558
629
  description?: string;
559
- slug?: string;
630
+ visibility?: PersonaWorkflowVisibility;
631
+ isEnabled?: boolean;
632
+ draft?: PersonaWorkflowDraft;
633
+ }
634
+ /** All fields optional — only what you pass is changed. */
635
+ interface UpdatePersonaWorkflowInput {
636
+ name?: string;
637
+ description?: string;
638
+ visibility?: PersonaWorkflowVisibility;
639
+ isEnabled?: boolean;
560
640
  draft?: PersonaWorkflowDraft;
561
- triggers?: PersonaWorkflowTrigger[];
562
- visibility?: "private" | "public";
563
- tags?: string[];
564
641
  }
565
- type UpdateWorkflowInput = Partial<CreateWorkflowInput>;
566
642
  interface UseWorkflowsOptions {
567
643
  autoFetch?: boolean;
568
- search?: string;
569
- status?: string;
570
644
  page?: number;
571
645
  limit?: number;
646
+ /** Free-text match against name/description. */
647
+ search?: string;
648
+ /** @default 'all' for a ProjectMachine/Admin caller; 'public' for a ProjectRuntime caller without this set. */
649
+ scope?: "mine" | "public" | "all";
650
+ visibility?: PersonaWorkflowVisibility;
651
+ isEnabled?: boolean;
572
652
  }
573
653
  interface UseWorkflowOptions {
574
654
  autoFetch?: boolean;
@@ -907,6 +987,213 @@ interface UseRcpSourcesOptions {
907
987
  /** Free-text match against name. */
908
988
  search?: string;
909
989
  }
990
+ /** One uploaded source document's chunking summary (not the chunks themselves). */
991
+ interface PersonaKnowledgeDocument {
992
+ fileName: string;
993
+ fileSize: number;
994
+ mimeType: string;
995
+ chunkCount: number;
996
+ uploadedAt: string;
997
+ }
998
+ interface PersonaKnowledgeBase {
999
+ _id: string;
1000
+ domain: string;
1001
+ ownerType: "PersonaUser" | "Project" | "ExternalUser";
1002
+ ownerId?: string;
1003
+ externalOwnerId?: string;
1004
+ name: string;
1005
+ description?: string;
1006
+ isPublic: boolean;
1007
+ documentCount: number;
1008
+ chunkCount: number;
1009
+ /** Internal vector-store collection name backing this Knowledge Base — informational only. */
1010
+ qdrantCollectionName: string;
1011
+ documents: PersonaKnowledgeDocument[];
1012
+ embeddingModel: string;
1013
+ providerId?: string;
1014
+ /** Characters per chunk, used when splitting uploaded documents. */
1015
+ chunkSize: number;
1016
+ /** Character overlap between adjacent chunks. */
1017
+ chunkOverlap: number;
1018
+ /** Default number of chunks returned per `search()` call when the caller doesn't override `topK`. */
1019
+ topK: number;
1020
+ createdAt: string;
1021
+ updatedAt: string;
1022
+ }
1023
+ interface CreatePersonaKnowledgeBaseInput {
1024
+ name: string;
1025
+ description?: string;
1026
+ /** @default false */
1027
+ isPublic?: boolean;
1028
+ /** @default 'text-embedding-3-small' */
1029
+ embeddingModel?: string;
1030
+ /** Must reference a Provider the host Project already created. */
1031
+ providerId: string;
1032
+ /** @default 800 */
1033
+ chunkSize?: number;
1034
+ /** @default 100 */
1035
+ chunkOverlap?: number;
1036
+ /** @default 5 */
1037
+ topK?: number;
1038
+ }
1039
+ /** All fields optional — only what you pass is changed. Does not retroactively re-embed existing documents. */
1040
+ interface UpdatePersonaKnowledgeBaseInput {
1041
+ name?: string;
1042
+ description?: string;
1043
+ isPublic?: boolean;
1044
+ embeddingModel?: string;
1045
+ providerId?: string;
1046
+ chunkSize?: number;
1047
+ chunkOverlap?: number;
1048
+ topK?: number;
1049
+ }
1050
+ interface PersonaUploadDocumentsResult {
1051
+ /** Total document count for the Knowledge Base after this upload (not just this call's files). */
1052
+ documentCount: number;
1053
+ /** Total chunk count for the Knowledge Base after this upload. */
1054
+ chunkCount: number;
1055
+ files: Array<{
1056
+ fileName: string;
1057
+ fileSize: number;
1058
+ mimeType: string;
1059
+ chunkCount: number;
1060
+ }>;
1061
+ }
1062
+ interface PersonaDeleteDocumentResult {
1063
+ removedChunks: number;
1064
+ remainingDocuments: number;
1065
+ remainingChunks: number;
1066
+ }
1067
+ interface PersonaKnowledgeSearchResult {
1068
+ text: string;
1069
+ /** The `fileName` of the source document this chunk came from. */
1070
+ source: string;
1071
+ /** Similarity score (higher is more relevant); `null` if the underlying store didn't return one. */
1072
+ score: number | null;
1073
+ }
1074
+ /** Agents referencing a Knowledge Base — check before deleting it to avoid a blocked-delete error. */
1075
+ interface PersonaKnowledgeBaseUsage {
1076
+ agentCount: number;
1077
+ agents: Array<{
1078
+ _id: string;
1079
+ name: string;
1080
+ }>;
1081
+ }
1082
+ interface UseKnowledgeBasesOptions {
1083
+ /** @default true */
1084
+ autoFetch?: boolean;
1085
+ page?: number;
1086
+ limit?: number;
1087
+ /** Free-text match against name/description. */
1088
+ search?: string;
1089
+ /** Restricts to the asserted external user's own Knowledge Bases. Requires a `ProjectRuntimeContext` — a no-op otherwise. */
1090
+ scope?: "mine";
1091
+ }
1092
+ type PersonaMcpTransport = "http" | "sse";
1093
+ type PersonaMcpAuthType = "none" | "oauth" | "apiKey";
1094
+ /** `owner`: one shared connection for the whole MCP. `user`: each external user connects their own. */
1095
+ type PersonaMcpAuthMode = "owner" | "user";
1096
+ interface PersonaMcpTool {
1097
+ name: string;
1098
+ description: string;
1099
+ }
1100
+ interface PersonaMcpResourceSummary {
1101
+ uri: string;
1102
+ name: string;
1103
+ description: string;
1104
+ mimeType: string;
1105
+ }
1106
+ /** A resource whose `uri` has placeholder params to fill before calling `readResource()`. */
1107
+ interface PersonaMcpResourceTemplate {
1108
+ uriTemplate: string;
1109
+ name: string;
1110
+ description: string;
1111
+ mimeType: string;
1112
+ toolName: string;
1113
+ }
1114
+ interface PersonaMcpOAuthConfig {
1115
+ clientId: string | null;
1116
+ hasClientSecret: boolean;
1117
+ authorizationEndpoint: string | null;
1118
+ tokenEndpoint: string | null;
1119
+ scopes: string[];
1120
+ dynamicallyRegistered: boolean;
1121
+ /** Whether this MCP's owner has completed the owner-mode OAuth flow. */
1122
+ ownerConnected: boolean;
1123
+ }
1124
+ /** Your own MCP server connection — a self-serve tool endpoint you registered, not one of the Project's shared ones (see `useMcp`/`useMcpConnections` for those). */
1125
+ interface PersonaMcp {
1126
+ _id: string;
1127
+ domain: string;
1128
+ ownerType: "PersonaUser" | "Project" | "ExternalUser";
1129
+ ownerId?: string;
1130
+ externalOwnerId?: string;
1131
+ name: string;
1132
+ description?: string;
1133
+ transport: PersonaMcpTransport;
1134
+ url: string;
1135
+ authType: PersonaMcpAuthType;
1136
+ authMode: PersonaMcpAuthMode;
1137
+ hasApiKey: boolean;
1138
+ oauth?: PersonaMcpOAuthConfig;
1139
+ isEnabled: boolean;
1140
+ /** Populated by `testConnection()`; empty until it's been called at least once. */
1141
+ tools: PersonaMcpTool[];
1142
+ resources: PersonaMcpResourceSummary[];
1143
+ resourceTemplates: PersonaMcpResourceTemplate[];
1144
+ createdAt: string;
1145
+ updatedAt: string;
1146
+ }
1147
+ interface PersonaMcpOAuthInput {
1148
+ clientId: string;
1149
+ clientSecret: string;
1150
+ scopes?: string[];
1151
+ }
1152
+ interface CreatePersonaMcpInput {
1153
+ name: string;
1154
+ transport: PersonaMcpTransport;
1155
+ url: string;
1156
+ description?: string;
1157
+ /** @default 'none' */
1158
+ authType?: PersonaMcpAuthType;
1159
+ /** @default 'owner' */
1160
+ authMode?: PersonaMcpAuthMode;
1161
+ /** Required when `authType: 'oauth'` and `useDynamicRegistration` isn't set. */
1162
+ oauth?: PersonaMcpOAuthInput;
1163
+ /** Required when `authType: 'apiKey'`. */
1164
+ apiKey?: string;
1165
+ /** Use RFC 7591 Dynamic Client Registration instead of a manually-configured `oauth` block. @default false */
1166
+ useDynamicRegistration?: boolean;
1167
+ /** @default true */
1168
+ isEnabled?: boolean;
1169
+ }
1170
+ /** All fields optional — only what you pass is changed. */
1171
+ interface UpdatePersonaMcpInput {
1172
+ name?: string;
1173
+ description?: string;
1174
+ transport?: PersonaMcpTransport;
1175
+ url?: string;
1176
+ authType?: PersonaMcpAuthType;
1177
+ authMode?: PersonaMcpAuthMode;
1178
+ isEnabled?: boolean;
1179
+ useDynamicRegistration?: boolean;
1180
+ oauth?: Partial<PersonaMcpOAuthInput>;
1181
+ /** Replaces the stored key entirely; omit to leave the existing key untouched. */
1182
+ apiKey?: string;
1183
+ }
1184
+ interface PersonaMcpTestConnectionResult {
1185
+ tools: PersonaMcpTool[];
1186
+ resources: PersonaMcpResourceSummary[];
1187
+ resourceTemplates: PersonaMcpResourceTemplate[];
1188
+ }
1189
+ interface UseMcpAdminOptions {
1190
+ /** @default true */
1191
+ autoFetch?: boolean;
1192
+ page?: number;
1193
+ limit?: number;
1194
+ /** Free-text match against name/description. */
1195
+ search?: string;
1196
+ }
910
1197
 
911
1198
  interface PersonaContextValue {
912
1199
  baseUrl: string;
@@ -1049,6 +1336,28 @@ declare function useThreads(autoFetch?: boolean): {
1049
1336
  getThread: (threadId: string) => Promise<PersonaThread>;
1050
1337
  };
1051
1338
 
1339
+ /**
1340
+ * CRUD over one Thread's workspace files (the agent's own virtual
1341
+ * filesystem) — `useChat()` already exposes a read-only `files` snapshot
1342
+ * tied to that thread's live/loaded messages; this hook is for a
1343
+ * standalone file-explorer UI that needs to list, read, write, and delete
1344
+ * files independently of an active chat session.
1345
+ *
1346
+ * KNOWN LIMITATION (inherited from the backend): no lock exists against a
1347
+ * concurrent live run on the same Thread — writing here while the agent is
1348
+ * actively mid-run could race with its own file writes.
1349
+ */
1350
+ declare function useWorkspaceFiles(threadId: string | undefined, autoFetch?: boolean): {
1351
+ files: Record<string, PersonaWorkspaceFile>;
1352
+ isLoading: boolean;
1353
+ isSaving: boolean;
1354
+ error: Error | null;
1355
+ refetch: () => Promise<Record<string, PersonaWorkspaceFile>>;
1356
+ getFile: (path: string) => Promise<PersonaWorkspaceFile>;
1357
+ writeFile: (path: string, content: string) => Promise<PersonaWorkspaceFile>;
1358
+ deleteFile: (path: string) => Promise<void>;
1359
+ };
1360
+
1052
1361
  /**
1053
1362
  * Drives a real-time voice call with an Agent (powered by Gemini Live).
1054
1363
  *
@@ -1248,39 +1557,130 @@ declare function useRcpSources(options?: UseRcpSourcesOptions): {
1248
1557
  testRcpSourceConnection: (sourceId: string) => Promise<PersonaRcpSourceTestResult>;
1249
1558
  };
1250
1559
 
1560
+ interface UploadKnowledgeDocumentInput {
1561
+ filename: string;
1562
+ /** Browser `File`/`Blob`, or a React Native `{ uri, name, type }`-style asset. */
1563
+ content: Blob | {
1564
+ uri: string;
1565
+ name?: string;
1566
+ type?: string;
1567
+ };
1568
+ contentType?: string;
1569
+ }
1570
+ /**
1571
+ * CRUD for Knowledge Bases — vector-search-backed document collections an
1572
+ * Agent can be given. Requires the host's `createPersonaHandler`/
1573
+ * `createRuntime` to opt in with `capabilities: { knowledge: true }`;
1574
+ * every route this hook calls 404s/is unreachable otherwise.
1575
+ *
1576
+ * Ownership follows the same self-serve model as `useSkills`/`useAgents`:
1577
+ * pass `scope: 'mine'` to restrict `knowledgeBases` to the asserted
1578
+ * external user's own Knowledge Bases — omit it to see every one visible
1579
+ * to this Project (its own, plus public ones).
1580
+ */
1581
+ declare function useKnowledgeBases(options?: UseKnowledgeBasesOptions): {
1582
+ knowledgeBases: PersonaKnowledgeBase[];
1583
+ pagination: PersonaPagination;
1584
+ isLoading: boolean;
1585
+ isUploading: boolean;
1586
+ error: Error | null;
1587
+ refetch: () => Promise<PersonaKnowledgeBase[]>;
1588
+ getKnowledgeBase: (kbId: string) => Promise<PersonaKnowledgeBase>;
1589
+ createKnowledgeBase: (input: CreatePersonaKnowledgeBaseInput) => Promise<PersonaKnowledgeBase>;
1590
+ updateKnowledgeBase: (kbId: string, input: UpdatePersonaKnowledgeBaseInput) => Promise<PersonaKnowledgeBase>;
1591
+ deleteKnowledgeBase: (kbId: string) => Promise<void>;
1592
+ bulkDeleteKnowledgeBases: (ids: string[]) => Promise<PersonaBulkDeleteResult>;
1593
+ getKnowledgeBaseUsage: (kbId: string) => Promise<PersonaKnowledgeBaseUsage>;
1594
+ uploadDocuments: (kbId: string, files: UploadKnowledgeDocumentInput[]) => Promise<PersonaUploadDocumentsResult>;
1595
+ listDocuments: (kbId: string) => Promise<PersonaKnowledgeDocument[]>;
1596
+ deleteDocument: (kbId: string, sourceName: string) => Promise<PersonaDeleteDocumentResult>;
1597
+ search: (kbId: string, query: string, opts?: {
1598
+ topK?: number;
1599
+ }) => Promise<PersonaKnowledgeSearchResult[]>;
1600
+ };
1601
+
1602
+ /**
1603
+ * Self-serve CRUD for the calling end user's OWN MCP server connections —
1604
+ * "connect your own tool server to your agent", not the Project's shared
1605
+ * ones (see `useMcp` for calling tools/reading resources on an already-
1606
+ * attached MCP, and `useMcpConnections` for the per-user OAuth connect/
1607
+ * disconnect flow on a Project-configured `authMode: 'user'` MCP).
1608
+ *
1609
+ * Requires the host's `createPersonaHandler`/`createRuntime` to opt in
1610
+ * with `capabilities: { mcps: true }`; every route this hook calls
1611
+ * 404s/is unreachable otherwise.
1612
+ *
1613
+ * Deliberately narrower than `useSkills`/`useAgents`/`useKnowledgeBases`:
1614
+ * always operates in "mine" mode — `list()` only ever returns MCPs the
1615
+ * calling external user themselves registered (there's no `scope` option
1616
+ * to browse the Project's shared MCPs; an end user managing their own tool
1617
+ * connections has no reason to browse someone else's). `createMcp` always
1618
+ * creates as their own — ownership is resolved server-side from the
1619
+ * asserted external user, never something you pass in. No `getUsage` —
1620
+ * unlike a Skill/Agent, other people's Agents can't reference a personal
1621
+ * MCP only its owner can see.
1622
+ */
1623
+ declare function useMcpAdmin(options?: UseMcpAdminOptions): {
1624
+ mcps: PersonaMcp[];
1625
+ pagination: PersonaPagination;
1626
+ isLoading: boolean;
1627
+ error: Error | null;
1628
+ refetch: () => Promise<PersonaMcp[]>;
1629
+ getMcp: (mcpId: string) => Promise<PersonaMcp>;
1630
+ createMcp: (input: CreatePersonaMcpInput) => Promise<PersonaMcp>;
1631
+ updateMcp: (mcpId: string, input: UpdatePersonaMcpInput) => Promise<PersonaMcp>;
1632
+ deleteMcp: (mcpId: string) => Promise<void>;
1633
+ bulkDeleteMcps: (ids: string[]) => Promise<PersonaBulkDeleteResult>;
1634
+ testConnection: (mcpId: string) => Promise<PersonaMcpTestConnectionResult>;
1635
+ };
1636
+
1251
1637
  interface WorkflowsPagination {
1252
1638
  page: number;
1253
1639
  limit: number;
1254
1640
  total: number;
1255
1641
  totalPages: number;
1256
1642
  }
1643
+ /**
1644
+ * Read-only discovery (`workflows`) is always on. `createWorkflow` requires
1645
+ * the host's `createPersonaHandler`/`createRuntime` to opt in with
1646
+ * `capabilities: { workflowsWrite: true }` — otherwise that one route
1647
+ * 404s/is unreachable (authoring workflows is Project-admin/builder work,
1648
+ * not something an ordinary end-user session does by default).
1649
+ */
1257
1650
  declare function useWorkflows(options?: UseWorkflowsOptions | boolean): {
1258
- workflows: PersonaWorkflowSummary[];
1651
+ workflows: PersonaWorkflow[];
1259
1652
  pagination: WorkflowsPagination;
1260
1653
  isLoading: boolean;
1261
1654
  error: Error | null;
1262
- refetch: () => Promise<PersonaWorkflowSummary[]>;
1263
- createWorkflow: (input: CreateWorkflowInput) => Promise<PersonaWorkflow>;
1655
+ refetch: () => Promise<PersonaWorkflow[]>;
1656
+ createWorkflow: (input: CreatePersonaWorkflowInput) => Promise<PersonaWorkflow>;
1264
1657
  };
1265
1658
 
1659
+ /**
1660
+ * Single-workflow read + the full `capabilities.workflowsWrite`-gated
1661
+ * authoring surface: metadata update, draft autosave, publish, version
1662
+ * history, and Mermaid export.
1663
+ */
1266
1664
  declare function useWorkflow(workflowId: string, options?: UseWorkflowOptions | boolean): {
1267
1665
  workflow: PersonaWorkflow | null;
1268
- versions: PersonaWorkflowVersionSummary[];
1666
+ versions: PersonaWorkflowVersion[];
1269
1667
  mermaid: string | null;
1270
1668
  isLoading: boolean;
1271
1669
  error: Error | null;
1272
1670
  refetch: () => Promise<PersonaWorkflow | null>;
1273
- fetchVersions: () => Promise<PersonaWorkflowVersionSummary[]>;
1671
+ fetchVersions: () => Promise<PersonaWorkflowVersion[]>;
1672
+ getVersion: (version: number) => Promise<PersonaWorkflowVersion>;
1274
1673
  fetchMermaid: () => Promise<any>;
1674
+ updateWorkflow: (input: UpdatePersonaWorkflowInput) => Promise<PersonaWorkflow>;
1275
1675
  saveDraft: (draft: PersonaWorkflowDraft) => Promise<PersonaWorkflow>;
1276
- publish: (summary?: string) => Promise<PersonaWorkflowVersionSummary>;
1676
+ publish: () => Promise<PersonaWorkflowVersion>;
1277
1677
  deleteWorkflow: () => Promise<void>;
1278
1678
  };
1279
1679
 
1280
1680
  declare function useWorkflowStream(workflowId?: string, options?: UseWorkflowStreamOptions): UseWorkflowStreamResult;
1281
1681
 
1282
1682
  declare function useWorkflowRuns(workflowId?: string, options?: UseWorkflowRunsOptions | boolean): {
1283
- runs: PersonaWorkflowRunSummary[];
1683
+ runs: PersonaWorkflowRun[];
1284
1684
  pagination: {
1285
1685
  page: number;
1286
1686
  limit: number;
@@ -1289,8 +1689,8 @@ declare function useWorkflowRuns(workflowId?: string, options?: UseWorkflowRunsO
1289
1689
  };
1290
1690
  isLoading: boolean;
1291
1691
  error: Error | null;
1292
- refetch: () => Promise<PersonaWorkflowRunSummary[]>;
1293
- getRun: (runId: string) => Promise<PersonaWorkflowRunSummary>;
1692
+ refetch: () => Promise<PersonaWorkflowRun[]>;
1693
+ getRun: (runId: string) => Promise<PersonaWorkflowRun>;
1294
1694
  cancelRun: (runId: string) => Promise<void>;
1295
1695
  };
1296
1696
 
@@ -1353,4 +1753,4 @@ declare function openSSEStream(opts: OpenSSEOptions): Promise<SSEStream>;
1353
1753
 
1354
1754
  declare const VERSION = "0.10.0";
1355
1755
 
1356
- export { ARCHITECT_AGENT_ID, type CreatePersonaAgentInput, type CreatePersonaRcpSourceInput, type CreatePersonaSkillInput, type CreateWorkflowInput, type OpenSSEOptions, type PersonaAgent, type PersonaAgentCategory, type PersonaAgentSocialLinks, type PersonaAgentVisibility, type PersonaBulkDeleteResult, type PersonaClarificationQuestion, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaMcpConnection, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaNodeRunState, type PersonaPagination, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaRcpParamContextMapEntry, type PersonaRcpSource, type PersonaRcpSourceTestResult, type PersonaRcpSourceToolParamSummary, type PersonaRcpSourceToolSummary, type PersonaResourceUsage, type PersonaResumeValue, type PersonaRole, type PersonaSandboxCommand, type PersonaSkill, type PersonaSkillFile, type PersonaSkillUsage, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkflow, type PersonaWorkflowDraft, type PersonaWorkflowEdge, type PersonaWorkflowNode, type PersonaWorkflowNodeType, type PersonaWorkflowRunSummary, type PersonaWorkflowSummary, type PersonaWorkflowTrigger, type PersonaWorkflowVersionSummary, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendArchitectMessageOverride, type SendMessageOverride, type UpdatePersonaAgentInput, type UpdatePersonaRcpSourceInput, type UpdatePersonaSkillInput, type UpdateWorkflowInput, type UseAgentsOptions, type UseArchitectChatOptions, type UseChatOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseRcpSourcesOptions, type UseSkillsOptions, type UseVoiceOptions, type UseVoiceResult, type UseWorkflowOptions, type UseWorkflowRunsOptions, type UseWorkflowStreamOptions, type UseWorkflowStreamResult, type UseWorkflowsOptions, VERSION, type WorkflowsPagination, openSSEStream, supportsStreamingFetch, useAgents, useArchitectChat, useChat, useConnection, useFiles, useMcp, useMcpConnections, useMemory, usePersonaContext, useRcpSources, useSkills, useThreads, useVoice, useWorkflow, useWorkflowRuns, useWorkflowStream, useWorkflows };
1756
+ export { ARCHITECT_AGENT_ID, type CreatePersonaAgentInput, type CreatePersonaKnowledgeBaseInput, type CreatePersonaMcpInput, type CreatePersonaRcpSourceInput, type CreatePersonaSkillInput, type CreatePersonaWorkflowInput, type OpenSSEOptions, type PersonaAgent, type PersonaAgentCategory, type PersonaAgentSnapshot, type PersonaAgentSocialLinks, type PersonaAgentVisibility, type PersonaBulkDeleteResult, type PersonaClarificationQuestion, type PersonaDeleteDocumentResult, type PersonaFileItem, type PersonaHealthInfo, type PersonaHitlActionRequest, type PersonaInterrupt, type PersonaKnowledgeBase, type PersonaKnowledgeBaseUsage, type PersonaKnowledgeDocument, type PersonaKnowledgeSearchResult, type PersonaMcp, type PersonaMcpAuthMode, type PersonaMcpAuthType, type PersonaMcpConnection, type PersonaMcpOAuthConfig, type PersonaMcpOAuthInput, type PersonaMcpResourceSummary, type PersonaMcpResourceTemplate, type PersonaMcpTestConnectionResult, type PersonaMcpTool, type PersonaMcpTransport, type PersonaMemoryAgentGroup, type PersonaMemoryFile, type PersonaMemoryList, type PersonaMessage, type PersonaNodeOnErrorAction, type PersonaNodeRetryPolicy, type PersonaNodeRun, type PersonaNodeRunState, type PersonaNodeRunStatus, type PersonaPagination, type PersonaPresentedFile, PersonaProvider, type PersonaProviderProps, type PersonaRcpParamContextMapEntry, type PersonaRcpSource, type PersonaRcpSourceTestResult, type PersonaRcpSourceToolParamSummary, type PersonaRcpSourceToolSummary, type PersonaResourceUsage, type PersonaResumeValue, type PersonaRole, type PersonaSandboxCommand, type PersonaSkill, type PersonaSkillFile, type PersonaSkillUsage, type PersonaStreamingEvent, type PersonaSubagentActivityEntry, type PersonaThread, type PersonaTodo, type PersonaToolCall, type PersonaUploadDocumentsResult, type PersonaVoiceEndReason, type PersonaVoiceState, type PersonaVoiceToolCall, type PersonaVoiceTranscriptLine, type PersonaWorkflow, type PersonaWorkflowDraft, type PersonaWorkflowEdge, type PersonaWorkflowNode, type PersonaWorkflowNodeData, type PersonaWorkflowNodeType, type PersonaWorkflowOwnerType, type PersonaWorkflowRun, type PersonaWorkflowRunStatus, type PersonaWorkflowTrigger, type PersonaWorkflowTriggerType, type PersonaWorkflowUsage, type PersonaWorkflowVersion, type PersonaWorkflowVisibility, type PersonaWorkspaceFile, type SSEReader, type SSEStream, type SendArchitectMessageOverride, type SendMessageOverride, type UpdatePersonaAgentInput, type UpdatePersonaKnowledgeBaseInput, type UpdatePersonaMcpInput, type UpdatePersonaRcpSourceInput, type UpdatePersonaSkillInput, type UpdatePersonaWorkflowInput, type UploadKnowledgeDocumentInput, type UseAgentsOptions, type UseArchitectChatOptions, type UseChatOptions, type UseKnowledgeBasesOptions, type UseMcpAdminOptions, type UseMcpConnectionsOptions, type UseMcpOptions, type UseRcpSourcesOptions, type UseSkillsOptions, type UseVoiceOptions, type UseVoiceResult, type UseWorkflowOptions, type UseWorkflowRunsOptions, type UseWorkflowStreamOptions, type UseWorkflowStreamResult, type UseWorkflowsOptions, VERSION, type WorkflowsPagination, openSSEStream, supportsStreamingFetch, useAgents, useArchitectChat, useChat, useConnection, useFiles, useKnowledgeBases, useMcp, useMcpAdmin, useMcpConnections, useMemory, usePersonaContext, useRcpSources, useSkills, useThreads, useVoice, useWorkflow, useWorkflowRuns, useWorkflowStream, useWorkflows, useWorkspaceFiles };