@collective-intelligence/external-apps-server-sdk 0.3.1 → 0.3.3

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.ts CHANGED
@@ -64,6 +64,47 @@ export declare class MemberSessionExchangeError extends MemberSessionExchangeErr
64
64
  }>, options: Schema.MakeOptions | undefined);
65
65
  get message(): string;
66
66
  }
67
+ export type Suspend1 = {
68
+ fieldId: string;
69
+ kind: "predicate";
70
+ operator: "eq" | "ne" | "lt" | "lte" | "gt" | "gte" | "in" | "not_in" | "is_null" | "is_not_null" | "contains" | "starts_with";
71
+ values: Array<{
72
+ kind: "null";
73
+ } | {
74
+ kind: "boolean";
75
+ value: boolean;
76
+ } | {
77
+ kind: "string";
78
+ value: string;
79
+ } | {
80
+ kind: "int64";
81
+ value: string;
82
+ } | {
83
+ kind: "float64";
84
+ value: number;
85
+ } | {
86
+ kind: "decimal";
87
+ value: string;
88
+ } | {
89
+ kind: "date";
90
+ value: string;
91
+ } | {
92
+ kind: "timestamp";
93
+ value: string;
94
+ } | {
95
+ kind: "duration";
96
+ value: string;
97
+ } | {
98
+ kind: "json";
99
+ value: unknown;
100
+ }>;
101
+ } | {
102
+ filters: Array<Suspend1>;
103
+ kind: "and" | "or";
104
+ } | {
105
+ filter: Suspend1;
106
+ kind: "not";
107
+ };
67
108
  export type AccessExplanation = {
68
109
  cut: {
69
110
  credential: {
@@ -171,6 +212,191 @@ export type AccessExplanation = {
171
212
  }>;
172
213
  recordId: string;
173
214
  schemaId: string;
215
+ } | {
216
+ datasetId: string;
217
+ kind: "dataset";
218
+ admitted: true;
219
+ audienceEntry: {
220
+ kind: "organization";
221
+ } | {
222
+ kind: "user";
223
+ userId: string;
224
+ } | {
225
+ coverage: "direct" | "inherited";
226
+ groupId: string;
227
+ kind: "group";
228
+ } | {
229
+ kind: "profile";
230
+ profileId: string;
231
+ } | {
232
+ applicationId: string;
233
+ kind: "application";
234
+ } | {
235
+ applicationId: string;
236
+ kind: "anonymous";
237
+ } | {
238
+ capabilityId: string;
239
+ kind: "capability";
240
+ mode: "manage" | "on" | "read";
241
+ };
242
+ policies: Array<{
243
+ grants: Array<{
244
+ grantId: string;
245
+ profileId: string;
246
+ }>;
247
+ policy: {
248
+ fqn: string;
249
+ id: string;
250
+ kind: "dataset_data_policy";
251
+ } | {
252
+ id: string;
253
+ kind: "core_admin" | "core_default" | "core_tenant";
254
+ };
255
+ }>;
256
+ readableFields: Array<string> | null;
257
+ rowRule: {
258
+ kind: "all";
259
+ } | {
260
+ filter: Suspend1;
261
+ kind: "filter";
262
+ };
263
+ } | {
264
+ datasetId: string;
265
+ kind: "dataset";
266
+ admitted: false;
267
+ reason: "not_in_audience";
268
+ } | {
269
+ datasetId: string;
270
+ kind: "dataset";
271
+ admitted: false;
272
+ audienceEntry: {
273
+ kind: "organization";
274
+ } | {
275
+ kind: "user";
276
+ userId: string;
277
+ } | {
278
+ coverage: "direct" | "inherited";
279
+ groupId: string;
280
+ kind: "group";
281
+ } | {
282
+ kind: "profile";
283
+ profileId: string;
284
+ } | {
285
+ applicationId: string;
286
+ kind: "application";
287
+ } | {
288
+ applicationId: string;
289
+ kind: "anonymous";
290
+ } | {
291
+ capabilityId: string;
292
+ kind: "capability";
293
+ mode: "manage" | "on" | "read";
294
+ };
295
+ reason: "no_active_revision" | "no_policy";
296
+ } | {
297
+ datasetId: string;
298
+ kind: "dataset";
299
+ admitted: false;
300
+ audienceEntry: {
301
+ kind: "organization";
302
+ } | {
303
+ kind: "user";
304
+ userId: string;
305
+ } | {
306
+ coverage: "direct" | "inherited";
307
+ groupId: string;
308
+ kind: "group";
309
+ } | {
310
+ kind: "profile";
311
+ profileId: string;
312
+ } | {
313
+ applicationId: string;
314
+ kind: "application";
315
+ } | {
316
+ applicationId: string;
317
+ kind: "anonymous";
318
+ } | {
319
+ capabilityId: string;
320
+ kind: "capability";
321
+ mode: "manage" | "on" | "read";
322
+ };
323
+ reason: "not_lowerable";
324
+ refusal: {
325
+ detail: string;
326
+ policyId: string;
327
+ reason: "operator" | "json_field" | "unknown_field" | "literal_type" | "operand" | "value_limit";
328
+ };
329
+ } | {
330
+ collectionId: string;
331
+ kind: "collection";
332
+ admitted: true;
333
+ audienceEntry: {
334
+ kind: "organization";
335
+ } | {
336
+ kind: "user";
337
+ userId: string;
338
+ } | {
339
+ coverage: "direct" | "inherited";
340
+ groupId: string;
341
+ kind: "group";
342
+ } | {
343
+ kind: "profile";
344
+ profileId: string;
345
+ } | {
346
+ applicationId: string;
347
+ kind: "application";
348
+ } | {
349
+ applicationId: string;
350
+ kind: "anonymous";
351
+ } | {
352
+ capabilityId: string;
353
+ kind: "capability";
354
+ mode: "manage" | "on" | "read";
355
+ };
356
+ opens: {
357
+ kind: "all";
358
+ } | {
359
+ folderIds: Array<string>;
360
+ kind: "folders";
361
+ };
362
+ policies: Array<{
363
+ folderId: string | null;
364
+ id: string;
365
+ kind: "core_admin" | "core_default" | "core_tenant" | "document_data_policy";
366
+ }>;
367
+ } | {
368
+ collectionId: string;
369
+ kind: "collection";
370
+ admitted: false;
371
+ reason: "not_in_audience";
372
+ } | {
373
+ collectionId: string;
374
+ kind: "collection";
375
+ admitted: false;
376
+ audienceEntry: {
377
+ kind: "organization";
378
+ } | {
379
+ kind: "user";
380
+ userId: string;
381
+ } | {
382
+ coverage: "direct" | "inherited";
383
+ groupId: string;
384
+ kind: "group";
385
+ } | {
386
+ kind: "profile";
387
+ profileId: string;
388
+ } | {
389
+ applicationId: string;
390
+ kind: "application";
391
+ } | {
392
+ applicationId: string;
393
+ kind: "anonymous";
394
+ } | {
395
+ capabilityId: string;
396
+ kind: "capability";
397
+ mode: "manage" | "on" | "read";
398
+ };
399
+ reason: "no_policy";
174
400
  };
175
401
  };
176
402
  export type AccessExplainRequest = {
@@ -196,6 +422,12 @@ export type AccessExplainRequest = {
196
422
  kind: "record";
197
423
  operation: "read" | "write";
198
424
  recordId: string;
425
+ } | {
426
+ datasetId: string;
427
+ kind: "dataset";
428
+ } | {
429
+ collectionId: string;
430
+ kind: "collection";
199
431
  };
200
432
  };
201
433
  export type AccessGrantAxis = {
@@ -512,6 +744,20 @@ export type AccessMemberPage = {
512
744
  items: Array<AccessMember>;
513
745
  next: string | null;
514
746
  };
747
+ export type AccessMemberHoldersRequest = {
748
+ axis: string;
749
+ profile: string | {
750
+ id: string;
751
+ };
752
+ value: {
753
+ knowledgeEntity: {
754
+ field: string;
755
+ value: string;
756
+ };
757
+ } | string;
758
+ after?: string;
759
+ limit?: number;
760
+ };
515
761
  export type ExternalApplicationsGetContextErrors = {
516
762
  /**
517
763
  * Error
@@ -618,6 +864,7 @@ export type ApplicationAccessMembersListData = {
618
864
  after?: string;
619
865
  email?: string;
620
866
  limit?: string;
867
+ name?: string;
621
868
  };
622
869
  url: "/application/v1/access/members";
623
870
  };
@@ -631,6 +878,16 @@ export type ApplicationAccessMembersCreateData = {
631
878
  query?: never;
632
879
  url: "/application/v1/access/members";
633
880
  };
881
+ export type ApplicationAccessMembersListHoldersData = {
882
+ body: AccessMemberHoldersRequest;
883
+ headers: {
884
+ authorization?: string;
885
+ "x-organization-id": string;
886
+ };
887
+ path?: never;
888
+ query?: never;
889
+ url: "/application/v1/access/members/holders";
890
+ };
634
891
  export type ApplicationAccessMembersDeleteData = {
635
892
  body?: never;
636
893
  headers: {
@@ -1787,6 +2044,7 @@ declare const createApplicationAccessApi: (client: Client$1) => {
1787
2044
  members: {
1788
2045
  create: (options: EndpointOptions<Options$1<ApplicationAccessMembersCreateData, false, unknown>>) => Promise<AccessMemberCreated>;
1789
2046
  get: (options: EndpointOptions<Options$1<ApplicationAccessMembersGetData, false, unknown>>) => Promise<AccessMember>;
2047
+ holders: (options: EndpointOptions<Options$1<ApplicationAccessMembersListHoldersData, false, unknown>>) => Promise<AccessMemberPage>;
1790
2048
  list: (options: EndpointOptions<Options$1<ApplicationAccessMembersListData, false, unknown>>) => Promise<AccessMemberPage>;
1791
2049
  remove: (options: EndpointOptions<Options$1<ApplicationAccessMembersDeleteData, false, unknown>>) => Promise<void>;
1792
2050
  resume: (options: EndpointOptions<Options$1<ApplicationAccessMembersResumeData, false, unknown>>) => Promise<void>;
@@ -1901,8 +2159,9 @@ export interface ServerAccessService {
1901
2159
  /**
1902
2160
  * Members and guests. `create` needs `admin.grants` at manage and Grant
1903
2161
  * Authority over each grant; reads need `admin.users` at read for
1904
- * members and `admin.guests` at read for guests; changes need the same at
1905
- * manage. An app server sees and changes only the guests it created.
2162
+ * members and `admin.guests` at read for guests; `holders` also needs
2163
+ * `admin.grants` at read; changes need the same at manage. An app server
2164
+ * sees and changes only the guests it created.
1906
2165
  */
1907
2166
  readonly members: Readonly<{
1908
2167
  create: Method<WithBody<Api["members"]["create"]>, Api["members"]["create"]>;
@@ -1911,6 +2170,15 @@ export interface ServerAccessService {
1911
2170
  email: string;
1912
2171
  }>, ServerAccessMember | null>;
1913
2172
  get: Method<WithPath<Api["members"]["get"]>, Api["members"]["get"]>;
2173
+ /**
2174
+ * The members that hold the profile (FQN or `{ id }`) on the Axis Value
2175
+ * of the Grant Axis `axis` (its slug) or on a value below it, through
2176
+ * their own or a Group grant; a grant above the value holds nothing
2177
+ * there. A suspended member is listed with `suspended: true`. A page in
2178
+ * user id order; pass `next` as `after` for the next.
2179
+ */
2180
+ holders: Method<WithBody<Api["members"]["holders"]>, Api["members"]["holders"]>;
2181
+ /** A page of members, by `email`, or by a `name` that holds the text without case; pass `next` as `after` for the next. */
1914
2182
  list: Method<ServerAccessContext & QueryOf<Api["members"]["list"]>, Api["members"]["list"]>;
1915
2183
  remove: Method<WithPath<Api["members"]["remove"]>, Api["members"]["remove"]>;
1916
2184
  resume: Method<WithPath<Api["members"]["resume"]>, Api["members"]["resume"]>;
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-vf83jqc8.js";var CiError=CiError2;var ServerAccessError=ServerAccessError2;var CiTransportError=CiTransportError2;var FederatedAuthError=FederatedAuthError2;export{CiError,CiTransportError,FederatedAuthError,MemberSessionExchangeError2 as MemberSessionExchangeError,ServerAccessError,createServerClient2 as createServerClient,exchangeMemberSession2 as exchangeMemberSession,runAsApplication2 as runAsApplication,serverSdkRuntime2 as serverSdkRuntime,uuidV72 as uuidV7};
1
+ import{ServerAccessError2,MemberSessionExchangeError2,CiError2,CiTransportError2,FederatedAuthError2,serverSdkRuntime2,createServerClient2,exchangeMemberSession2,runAsApplication2,uuidV72}from"./chunks/index-hzx6hj46.js";var CiError=CiError2;var ServerAccessError=ServerAccessError2;var CiTransportError=CiTransportError2;var FederatedAuthError=FederatedAuthError2;export{CiError,CiTransportError,FederatedAuthError,MemberSessionExchangeError2 as MemberSessionExchangeError,ServerAccessError,createServerClient2 as createServerClient,exchangeMemberSession2 as exchangeMemberSession,runAsApplication2 as runAsApplication,serverSdkRuntime2 as serverSdkRuntime,uuidV72 as uuidV7};
@@ -2,17 +2,17 @@
2
2
 
3
3
  Tools, Skills, Agents, workflows and Studio chat, how they compose, and how audiences, approvals, models, runs and timeouts behave.
4
4
 
5
- The `next-effect-app` template ships two AI features. Its Lead qualifier Agent scores how ready a Lead is to convert, and its convert-lead workflow marks a Lead converted when the web app asks. Both are built from the same small set of AI primitives, and a new demo feature usually starts as a copy of one of them. This page explains each primitive through those two features and ends with a table that helps you choose between them.
5
+ The `next-effect-app` template ships two AI features. Its Lead qualifier Agent scores how ready a Lead is to convert, and its convert-lead workflow is the smallest workflow that the web app can start. That workflow only sets a workflow variable and writes no Lead record, so it is a starting point for your own steps. Both are built from the same small set of AI primitives, and a new demo feature usually starts as a copy of one of them. This page explains each primitive through those two features and ends with a table that helps you choose between them.
6
6
 
7
7
  ## The building blocks
8
8
 
9
- | Building block | What it is | Model inside | How it starts |
10
- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
11
- | Tool | A typed, callable capability, such as a Knowledge query, a message send, a web search or your own package code. Tools are grouped in tool collections. | No | A Skill, an Agent, a workflow node or a chat turn calls it. |
12
- | Skill | Versioned instructions with model settings, permissions and a bounded set of tools, for one AI task. | Yes | Studio chat, a Studio Skill Form, the public Skill API, MCP, a workflow Skill node, or an Agent that holds it. |
13
- | Agent | An Organization-owned actor with a Role, held Skills, its own tools and an optional typed output. | Yes | Your server invokes it, a conversation continues it, or an event, a delegation, a schedule or a heartbeat triggers it. |
14
- | Workflow | A durable graph of steps with triggers, versions, runs, pauses and approvals. | Only in Prompt and Skill nodes | A trigger fires: webhook, schedule, Knowledge record event, external application, MCP operation or on demand. |
15
- | Studio chat | The Studio conversation in which Organization members use the tools and Skills offered to them. | Yes | A member sends a message. |
9
+ | Building block | What it is | Model inside | How it starts |
10
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
11
+ | Tool | A typed, callable capability, such as a Knowledge query, a message send, a web search or your own package code. Tools are grouped in tool collections. | No | A Skill, an Agent, a workflow node or a chat turn calls it. |
12
+ | Skill | Versioned instructions with model settings, permissions and a bounded set of tools, for one AI task. | Yes | Studio chat, a Studio Skill Form, the public Skill API, MCP, a workflow Skill node, or an Agent that holds it. |
13
+ | Agent | An Organization-owned actor with a Role, held Skills, its own tools and an optional typed output. | Yes | Your server invokes it, a person talks to it in Studio, or an event or a delegation from another Agent starts it. |
14
+ | Workflow | A durable graph of steps with triggers, versions, runs, pauses and approvals. | Only in Prompt and Skill nodes | A trigger fires: webhook, schedule, Knowledge record event, external application, MCP operation or on demand. |
15
+ | Studio chat | The conversation in [Studio](studio.md) in which Organization members use the agents, tools and Skills offered to them. | Yes | A member sends a message. |
16
16
 
17
17
  The template's Lead qualifier composes three of these. A package declares the Lead score tool, a Lead scoring Skill that binds it, and an Agent that holds the Skill and is offered to the external application:
18
18
 
@@ -67,7 +67,7 @@ declareTool({
67
67
 
68
68
  `usageScopes` decides where the tool can appear: in a Skill, in chat, or in automation. The template needs `automation` so that the Lead qualifier Agent can use the tool. When you omit `usageScopes`, the tool appears in all three places, and an explicit empty list makes it unavailable everywhere. The model reads `toolGuidance.useWhen` and `toolGuidance.inputRequirementsSummary` to decide when to call the tool and what to pass, so write both for the model.
69
69
 
70
- A demo can also bind built-in tools for web search (Exa or Tavily, which need an API key), website scraping, image generation, email, notifications, OCR, speech transcription and synthesis, and report building. External applications can use `publish-run-event`.
70
+ A package can also bind built-in tools for web search (Exa or Tavily, which need an API key), website scraping, image generation, email, notifications, OCR, speech transcription and synthesis, and report building. External applications can use `publish-run-event`.
71
71
 
72
72
  ## Skills
73
73
 
@@ -84,7 +84,7 @@ Score one Lead with the Lead score tool. Never guess a score.
84
84
  `
85
85
  ```
86
86
 
87
- The package passes these instructions to `declareSkill({ definition: { audience, instructions, lifecycle, tools } })`, and the template's `tools` list holds only the Lead score tool. CI stores each Skill as a versioned package, and runtime always uses the active approved version.
87
+ The package passes these instructions to `declareSkill({ definition: { audience, instructions, lifecycle, uses: { tools } } })`, and the template's `uses.tools` list holds only the Lead score tool. CI stores each Skill as a versioned package, and runtime always uses the active approved version.
88
88
 
89
89
  The same Skill can run in Studio chat, in a Studio Skill Form, through the public Skill API (`skills_invoke`, then `runs_get` or `runs_stream`), through MCP `run_skill`, in a workflow Skill node, and inside an Agent that holds it. A Skill version can pin a model. Without a pin, it uses the model that the running Organization sets for Skill turns, which defaults to the `balanced` tier. A pinned model that does not resolve is a configuration error, and CI does not fall back to another model.
90
90
 
@@ -122,9 +122,9 @@ Held Skills load on demand. At first the Agent sees only the catalog. When it ca
122
122
 
123
123
  `output: { schema }` takes a codec, so the app can keep one runtime schema in its contracts package. A succeeded run returns `{ message, output? }`. `message` is the final answer, and `output` is the structured Agent Output, already valid against the schema. `output` is absent when the run saved none, for example when the Agent asked a clarifying question.
124
124
 
125
- An Agent without `activity` is idle and runs only when something triggers it: an invoke call, a conversation turn, an event or a delegation. `activity: { heartbeat, schedule }` turns on either source when you set it to `true`. Every Agent that a package declares is an Organization Agent.
125
+ An Agent without `activity` is idle and runs only when something triggers it: an invoke call, a conversation turn, an event or a delegation. The SDK also accepts `activity: { heartbeat, schedule }`. Before a demo depends on a package Agent that runs on a schedule or a heartbeat, confirm it with one trial run. Every Agent that a package declares is an Organization Agent.
126
126
 
127
- FQN string references are not type-checked when you build. Install resolves them and rolls the package back when one is missing: each held Skill must be approved, each Agent or Skill tool must be an enabled tool of the Organization, and each audience reference must exist. Only an administrator can install a package that declares Agents or Skills.
127
+ FQN string references are not type-checked when you build. Install resolves them and rolls the package back when one is missing: each held Skill must be approved, each Agent or Skill tool must be an enabled tool of the Organization, and each audience reference must exist. Only a person can install a package that declares Agents or Skills; an install with no signed-in user fails.
128
128
 
129
129
  ## Audiences
130
130
 
@@ -167,7 +167,7 @@ uses: {
167
167
 
168
168
  `name`, `description` and `approval` work the same way for every tool. The model sees the Binding Description in place of the tool's own description. `settings` holds the tool's own options, and the tool's Binding Settings Form defines them, so install fails on a key that the form does not define. A field that the form marks with `x-fqn-of` takes FQNs, and install translates each FQN into the id of the installing Organization's record. Install fails when an FQN names no record of that Organization, and the error names every such FQN of the binding. A binding has no tool-specific property.
169
169
 
170
- `approval` has three modes. `"never"` makes no approval request for the binding. `"always"` pauses for an explicit decision by the user who started the call, and that user's eligibility to approve does not approve the call. `{ rule: "<rule name>" }` uses an approval rule of the installing Organization, with that rule's reviewers and expiry. Install fails when no rule has the name, so create the rule in the target Organization before you install a demo package that uses one.
170
+ `approval` has three modes. `"never"` makes no approval request for the binding. `"always"` pauses for an explicit decision by the user who started the call, and that user's eligibility to approve does not approve the call. `{ rule: "<rule name>" }` uses an approval rule of the installing Organization, with that rule's reviewers and expiry. Install fails when no rule has the name, so create the rule in the target Organization before you install a package that uses one.
171
171
 
172
172
  Approval pauses the call and leaves the tool visible. With `"always"`, the model still sees the tool definition and can decide to call it, and the call then waits for a person.
173
173
 
@@ -190,7 +190,7 @@ The same binding behaves differently for each kind of caller:
190
190
 
191
191
  An approval authorizes one attempt. It does not check the tool input and cannot make the call succeed: an approved Knowledge Query `search` call still fails when it has no `entitySchemaId`.
192
192
 
193
- The reviewer never becomes the identity that runs the tool. After approval, the call resumes as the original invoker, and CI rechecks that user's current Organization authority, so a changed action, a rejection, an expiry or revoked access blocks the call. When the recipients or destination of a send change between approval and send, CI does not send. It opens a fresh approval request under the original user, and that request needs a new decision. Reviewers see the facts of the pending action in Studio Notifications. CI freezes those facts when the request opens and shows secrets as omitted.
193
+ The reviewer never becomes the identity that runs the tool. After approval, the call resumes as the identity that started it, which can be a person, a service principal or an app server. CI rechecks that identity's current Organization authority, so a changed action, a rejection, an expiry or revoked access blocks the call. When the recipients or destination of a send change between approval and send, CI does not send. It opens a fresh approval request under the same identity, and that request needs a new decision. Reviewers see the facts of the pending action in Studio Notifications. CI freezes those facts when the request opens and shows secrets as omitted.
194
194
 
195
195
  ## Models
196
196
 
@@ -257,7 +257,25 @@ Its one action node sets a fixed patch and declares how it behaves on dry runs,
257
257
  }
258
258
  ```
259
259
 
260
- A triggered workflow needs an identity to run as, and CI publishes it only with one. The template declares `servicePrincipal({ fqn: convertLeadRunnerFqn, groups: [], name: "Convert lead runner", version })` and sets `servicePrincipalFqn` on the workflow, so every tool call in the workflow runs as that principal. A service principal has no user identity in the tool catalog, which means user-scoped tool bindings never match it. Give it a tool through an Organization binding or through a Group it belongs to.
260
+ A workflow with a trigger needs a run-as service principal, and CI publishes it only with one. The template declares `servicePrincipal({ fqn: convertLeadRunnerFqn, groups: [], name: "Convert lead runner", version })` and selects it with `runIdentity: { mode: "service_principal", servicePrincipal: convertLeadRunnerFqn }` on the workflow.
261
+
262
+ ### Who a run acts as
263
+
264
+ Every tool call in a run uses the current grants of the identity that the run acts as. A workflow's `runIdentity` decides that identity for a person's start. In `triggering_user` mode, the default, the run acts as the person who starts it. In `service_principal` mode, a production run that a person starts from Studio or the Dashboard acts as the workflow's run-as service principal. A test run from the workflow editor always keeps its author's identity. A workflow that runs with no person, from a schedule, an event or an app call in service mode, needs `service_principal` mode, and CI refuses to publish an Organization workflow whose schedule or event trigger has no identity to run as.
265
+
266
+ | How the run starts | The run acts as |
267
+ | --------------------------------------------------------------------------- | ---------------------------------------------- |
268
+ | A Studio trigger form, or Run in the Dashboard, in `triggering_user` mode | The signed-in person |
269
+ | A Studio trigger form, or Run in the Dashboard, in `service_principal` mode | The run-as service principal |
270
+ | A test run from the workflow editor | The author |
271
+ | An external application call with the user's delegated token | The signed-in user |
272
+ | An external application call in service mode or with `runAsApplication` | The run-as service principal |
273
+ | A schedule, a webhook, a Knowledge record event or an MCP operation | The run-as service principal |
274
+ | An Invoke Workflow node (a child workflow) | The identity of the run that started the child |
275
+
276
+ An external application call with a delegated token acts as the user in both modes. The template's web app calls convert-lead with the user's delegated token, so a convert run from the web app acts as the signed-in Sales manager and not as `convertLeadRunner`, although the workflow is in `service_principal` mode. Agents follow the same rule: an Agent run acts as the person or app that started it, and an Agent that delegates to another Agent passes on that identity. An approval reviewer never becomes the identity of a run.
277
+
278
+ A service principal has no user identity in the tool catalog, which means user-scoped tool bindings never match it. Give it a tool through an Organization binding or through a Group it belongs to.
261
279
 
262
280
  Each trigger has an invocation mode: `attach`, `detach`, or `await_result` with a `timeoutMs`. `detach` answers at once with a durable 202, and `await_result` waits up to its timeout. The convert-lead trigger uses `{ mode: "await_result", timeoutMs: 90_000 }`. The web app starts it from its server with `createFixedWorkflowRoute` from `@collective-intelligence/external-apps-server-sdk/next`. The server owns the workflow FQN, and the browser sends only the Lead id:
263
281
 
@@ -338,12 +356,12 @@ const dataAccess = {
338
356
  | --------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
339
357
  | Model inside | No | Yes | Yes | Only in Prompt and Skill nodes |
340
358
  | Who decides the steps | Your code | The model, guided by the instructions | The model, guided by the Role and held Skills | The graph you build |
341
- | How it starts | Another primitive or a chat turn calls it | Chat, Skill Form, API, MCP, workflow node or Agent | Your server, a conversation, an event, a delegation, a schedule or a heartbeat | Webhook, schedule, record event, external application, MCP or on demand |
359
+ | How it starts | Another primitive or a chat turn calls it | Chat, Skill Form, API, MCP, workflow node or Agent | Your server, a Studio conversation, an event or a delegation | Webhook, schedule, record event, external application, MCP or on demand |
342
360
  | Human approval | Set on its binding | The run pauses for a decision | Approved by default and recorded | Approval node |
343
361
  | Output | Typed by its output schema | The run's result | `message` plus typed `output` | The declared output contract |
344
362
  | Pick it when | You need one deterministic, typed action such as score, fetch or send | One AI task with a bounded tool set must run in several places | You need a long-lived Role with an audience, typed output, conversation history or unattended runs | The steps are fixed and you need triggers, approvals or a typed result |
345
363
 
346
- Most demo features combine these primitives. The Lead qualifier uses a deterministic tool, a Skill that tells the model how to use it, and an Agent that holds the Skill for the external application. Convert-lead is a workflow because its one step is fixed and the web app waits for the result, so it needs no model. When a workflow step needs AI, use a Prompt or Skill node. [Scenarios](../scenarios/index.md) walks through more demo cases.
364
+ Most features combine these primitives. The Lead qualifier uses a deterministic tool, a Skill that tells the model how to use it, and an Agent that holds the Skill for the external application. Convert-lead is a workflow because its one step is fixed and the web app waits for the result, so it needs no model. When a workflow step needs AI, use a Prompt or Skill node. [Scenarios](../scenarios/index.md) walks through more demo cases.
347
365
 
348
366
  ## Not covered here
349
367
 
@@ -351,6 +369,7 @@ This page does not cover Personal Agents (admins create them in the Dashboard),
351
369
 
352
370
  ## Related pages
353
371
 
372
+ - [Studio](studio.md)
354
373
  - [Knowledge](../data/knowledge.md)
355
374
  - [Datasets](../data/datasets.md)
356
375
  - [Extensions](../develop/extensions.md)