@omnara/sdk 0.1.48 → 0.1.50

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.
@@ -351,18 +351,57 @@ type ClientOptions = {
351
351
  * An agent config as a JSON object. This schema is the source of truth for agent configs: the server compiles YAML and JSON configs against it.
352
352
  */
353
353
  type AgentConfigDefinition = {
354
+ /**
355
+ * GitHub integration whose credentials the agent's machine processes use for Git and gh. Not passed to subagents.
356
+ */
354
357
  git_credentials?: AgentConfigDefinitionGitCredentials;
358
+ /**
359
+ * System prompt: the agent's job, boundaries, and when to ask a human.
360
+ */
355
361
  instruction: string;
362
+ /**
363
+ * Integrations that show the agent's questions and approvals outside the dashboard, keyed by integration name. Not passed to subagents.
364
+ */
356
365
  interaction_handlers?: AgentConfigDefinitionInteractionHandlers;
366
+ /**
367
+ * BYO machines and machine pools the agent can run commands on.
368
+ */
357
369
  machine_sources?: AgentConfigDefinitionMachineSources;
370
+ /**
371
+ * Maximum subagent nesting depth. Defaults to 1, so subagents cannot spawn their own.
372
+ */
358
373
  max_depth?: number;
374
+ /**
375
+ * Maximum active subagents across all keys. Unset means no overall limit.
376
+ */
359
377
  max_subagents?: number;
378
+ /**
379
+ * MCP servers the agent can use, keyed by server name. Their tools are named mcp__{server}__{tool}.
380
+ */
360
381
  mcp?: AgentConfigDefinitionMcpServers;
382
+ /**
383
+ * Project memory stores the agent can access at /memory/{name}/.
384
+ */
361
385
  memory_stores?: AgentConfigDefinitionMemoryStores;
386
+ /**
387
+ * Model the agent runs on, with optional overrides of its defaults.
388
+ */
362
389
  model: AgentConfigDefinitionModel;
390
+ /**
391
+ * Skills the agent can load. The project must own or be granted each one.
392
+ */
363
393
  skills?: AgentConfigDefinitionSkills;
394
+ /**
395
+ * Subagents the agent can spawn, keyed by name.
396
+ */
364
397
  subagents?: AgentConfigDefinitionSubagents;
398
+ /**
399
+ * Built-in and custom tools, keyed by tool name. {} enables a tool with its defaults.
400
+ */
365
401
  tools?: AgentConfigDefinitionTools;
402
+ /**
403
+ * Config format version. Optional; set it to pin the format.
404
+ */
366
405
  version?: 'v1';
367
406
  };
368
407
  /**
@@ -383,6 +422,9 @@ type AgentConfigToolsDefinition = {
383
422
  * Integration whose git credentials the agent's machines use.
384
423
  */
385
424
  type AgentConfigDefinitionGitCredentials = {
425
+ /**
426
+ * Name of a GitHub integration in the project.
427
+ */
386
428
  integration: string;
387
429
  /**
388
430
  * GitHub repository IDs the credentials can access. Defaults to every repository the installation can access.
@@ -406,27 +448,66 @@ type AgentConfigDefinitionInteractionHandlers = {
406
448
  [key: string]: AgentConfigDefinitionInteractionHandler;
407
449
  } | null;
408
450
  type AgentConfigDefinitionMcpAuth = {
451
+ /**
452
+ * AWS region to sign for. Required for sigv4 only.
453
+ */
409
454
  region?: string;
455
+ /**
456
+ * Secret holding the credential: generic for bearer, oauth_token_set for oauth, aws_credentials for sigv4.
457
+ */
410
458
  secret_id: string;
459
+ /**
460
+ * AWS service to sign for, such as aws-mcp. Required for sigv4 only.
461
+ */
411
462
  service?: string;
463
+ /**
464
+ * bearer sends a static token, oauth uses tokens from Omnara's MCP OAuth flow, and sigv4 signs requests with AWS SigV4.
465
+ */
412
466
  type: 'bearer' | 'oauth' | 'sigv4';
413
467
  };
414
468
  type AgentConfigDefinitionMcpServer = {
469
+ /**
470
+ * How to authenticate to the server. Omit if it needs none.
471
+ */
415
472
  auth?: AgentConfigDefinitionMcpAuth;
473
+ /**
474
+ * Whether tools are enabled unless overridden in tools. Defaults to true.
475
+ */
416
476
  default_enabled?: boolean | null;
477
+ /**
478
+ * Keep the server's tools out of context until tool_search loads them. Defaults to false.
479
+ */
417
480
  deferred?: boolean;
481
+ /**
482
+ * Default permission for the server's tools. Defaults to always_ask.
483
+ */
418
484
  permission?: AgentConfigDefinitionToolPermission;
485
+ /**
486
+ * Per-tool overrides, keyed by the tool's name on the server.
487
+ */
419
488
  tools?: {
420
489
  [key: string]: AgentConfigDefinitionMcpTool;
421
490
  };
491
+ /**
492
+ * HTTPS URL of the server's MCP endpoint.
493
+ */
422
494
  url: string;
423
495
  };
424
496
  type AgentConfigDefinitionMcpServers = {
425
497
  [key: string]: AgentConfigDefinitionMcpServer;
426
498
  } | null;
427
499
  type AgentConfigDefinitionMcpTool = {
500
+ /**
501
+ * Overrides the server's deferred setting. Null inherits it.
502
+ */
428
503
  deferred?: boolean | null;
504
+ /**
505
+ * Enables or hides the tool. Null follows the server's default_enabled.
506
+ */
429
507
  enabled?: boolean | null;
508
+ /**
509
+ * Overrides the server's permission for this tool.
510
+ */
430
511
  permission?: AgentConfigDefinitionToolPermission;
431
512
  };
432
513
  type AgentConfigDefinitionMachineSource = ({
@@ -434,67 +515,169 @@ type AgentConfigDefinitionMachineSource = ({
434
515
  } | {
435
516
  [key: string]: unknown;
436
517
  }) & {
518
+ /**
519
+ * Working directory for the agent's processes. Overrides the machine or pool default.
520
+ */
437
521
  cwd?: string;
522
+ /**
523
+ * Pools only. Delete a machine after this many idle minutes; 0 disables. Unset inherits the grant or pool setting.
524
+ */
438
525
  delete_after_idle_minutes?: 0 | number;
526
+ /**
527
+ * Describes this source to the agent.
528
+ */
439
529
  description?: string;
530
+ /**
531
+ * Environment variables for the agent's processes. A null value removes an inherited variable.
532
+ */
440
533
  env_overlay?: {
441
534
  [key in EnvironmentVariableName]?: string | null;
442
535
  } | null;
536
+ /**
537
+ * Pools only. Machines to create at launch. Defaults to 1 and cannot exceed max_machines.
538
+ */
443
539
  initial_num_machines?: number;
540
+ /**
541
+ * Pools only. vCPUs for new machines, within pool and project limits.
542
+ */
444
543
  machine_cpu?: number;
544
+ /**
545
+ * Pools only. Memory in MB for new machines, within pool and project limits.
546
+ */
445
547
  machine_memory_mb?: number;
548
+ /**
549
+ * Name of a BYO machine granted to the project. Set this or machine_pool_name.
550
+ */
446
551
  machine_name?: ResourceNameReference;
552
+ /**
553
+ * Name of a machine pool granted to the project. Set this or machine_name.
554
+ */
447
555
  machine_pool_name?: ResourceNameReference;
556
+ /**
557
+ * Pools only. Provider options applied over the pool and grant options.
558
+ */
448
559
  machine_provider_options_overlay?: {
449
560
  [key: string]: unknown;
450
561
  } | null;
562
+ /**
563
+ * Pools only. Most machines the agent can hold from this pool. Defaults to 1.
564
+ */
451
565
  max_machines?: number;
566
+ /**
567
+ * Environment variables set from secrets, keyed by variable name. A null value removes an inherited variable.
568
+ */
452
569
  secret_env_overlay?: {
453
570
  [key in EnvironmentVariableName]?: string | null;
454
571
  } | null;
455
572
  };
456
573
  type AgentConfigDefinitionMachineSources = Array<AgentConfigDefinitionMachineSource> | null;
457
574
  type AgentConfigDefinitionMemoryStore = {
575
+ /**
576
+ * Name of a memory store in the project.
577
+ */
458
578
  name: MemoryStoreName;
579
+ /**
580
+ * read, or read_write if the store also allows agent writes.
581
+ */
459
582
  access: 'read' | 'read_write';
460
583
  };
461
584
  type AgentConfigDefinitionMemoryStores = Array<AgentConfigDefinitionMemoryStore> | null;
462
585
  type AgentConfigDefinitionModel = {
586
+ /**
587
+ * Prompt caching: none, short (provider default), or long (extended where available). Unset uses the model's default.
588
+ */
463
589
  cache_retention?: 'none' | 'short' | 'long';
464
590
  /**
465
591
  * Context budget for input and output tokens. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit.
466
592
  */
467
593
  context_window_tokens?: number;
594
+ /**
595
+ * Default output allowance per request. Overrides the model's default; max_output_tokens is the cap.
596
+ */
468
597
  default_max_output_tokens?: number;
598
+ /**
599
+ * Configured model name under provider_config.
600
+ */
469
601
  name: ResourceNameReference;
602
+ /**
603
+ * Name of the organization's model provider.
604
+ */
470
605
  provider_config: ResourceNameReference;
606
+ /**
607
+ * Reasoning effort, such as low, medium, or high, for models that support it.
608
+ */
471
609
  reasoning?: {
610
+ /**
611
+ * Reasoning effort, such as low, medium, or high.
612
+ */
472
613
  effort: string;
473
614
  };
474
615
  };
475
616
  type AgentConfigDefinitionSkills = Array<string> | null;
476
617
  type AgentConfigDefinitionSubagent = {
618
+ /**
619
+ * Archive these subagents after this many idle minutes. Unset never archives them for being idle.
620
+ */
477
621
  archive_after_idle_minutes?: number;
622
+ /**
623
+ * Tells the model when to spawn this subagent.
624
+ */
478
625
  description?: string;
626
+ /**
627
+ * Changes to the subagent's instruction.
628
+ */
479
629
  instruction?: AgentConfigDefinitionSubagentInstruction;
630
+ /**
631
+ * Maximum active subagents from this key. Unset means no per-key limit.
632
+ */
480
633
  max_instances?: number;
634
+ /**
635
+ * Model overrides. Omit provider_config and name to keep the base model.
636
+ */
481
637
  model?: AgentConfigDefinitionSubagentModel;
638
+ /**
639
+ * Agent profile to launch from. Required when type is profile.
640
+ */
482
641
  profile?: ResourceNameReference;
642
+ /**
643
+ * profile launches from a profile's current config; self copies this agent's config.
644
+ */
483
645
  type: 'profile' | 'self';
484
646
  };
485
647
  type AgentConfigDefinitionSubagentInstruction = {
648
+ /**
649
+ * Text appended to the base instruction.
650
+ */
486
651
  append?: string;
487
652
  };
488
653
  type AgentConfigDefinitionSubagentModel = {
654
+ /**
655
+ * Overrides the base model's prompt caching.
656
+ */
489
657
  cache_retention?: 'none' | 'short' | 'long';
490
658
  /**
491
659
  * Context budget for input and output tokens. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit.
492
660
  */
493
661
  context_window_tokens?: number;
662
+ /**
663
+ * Overrides the base model's default output allowance.
664
+ */
494
665
  default_max_output_tokens?: number;
666
+ /**
667
+ * Configured model name. Set with provider_config to switch models.
668
+ */
495
669
  name?: ResourceNameReference;
670
+ /**
671
+ * Model provider name. Set with name to switch models.
672
+ */
496
673
  provider_config?: ResourceNameReference;
674
+ /**
675
+ * Overrides the base model's reasoning effort.
676
+ */
497
677
  reasoning?: {
678
+ /**
679
+ * Reasoning effort, such as low, medium, or high.
680
+ */
498
681
  effort: string;
499
682
  };
500
683
  };
@@ -502,28 +685,61 @@ type AgentConfigDefinitionSubagents = {
502
685
  [key: string]: AgentConfigDefinitionSubagent;
503
686
  } | null;
504
687
  type AgentConfigDefinitionTool = {
688
+ /**
689
+ * Keep the tool out of context until tool_search loads it. Defaults to false.
690
+ */
505
691
  deferred?: boolean;
692
+ /**
693
+ * Custom tools only. Tells the model what the tool does.
694
+ */
506
695
  description?: string;
696
+ /**
697
+ * Set to false to disable the tool, including default tools.
698
+ */
507
699
  enabled?: boolean | null;
700
+ /**
701
+ * Custom tools only. JSON Schema for the tool's arguments.
702
+ */
508
703
  input_schema?: AgentConfigDefinitionToolInputSchema;
704
+ /**
705
+ * Overrides the tool's default permission. GET /tool-catalog lists defaults and modes.
706
+ */
509
707
  permission?: AgentConfigDefinitionToolPermission;
708
+ /**
709
+ * built_in for an Omnara tool, custom for a tool your system runs.
710
+ */
510
711
  type?: 'built_in' | 'custom';
511
712
  };
512
713
  /**
513
714
  * A JSON Schema for the tool's input. Keywords beyond those listed, such as additionalProperties or description, are allowed.
514
715
  */
515
716
  type AgentConfigDefinitionToolInputSchema = {
717
+ /**
718
+ * Arguments, keyed by name, as JSON Schemas.
719
+ */
516
720
  properties?: {
517
721
  [key: string]: {
518
722
  [key: string]: unknown;
519
723
  };
520
724
  };
725
+ /**
726
+ * Names of required arguments.
727
+ */
521
728
  required?: Array<string>;
729
+ /**
730
+ * Root type of the argument schema.
731
+ */
522
732
  type: 'object';
523
733
  [key: string]: unknown;
524
734
  };
525
735
  type AgentConfigDefinitionToolPermission = {
736
+ /**
737
+ * always_allow, always_ask (wait for human approval), or always_deny.
738
+ */
526
739
  mode: string;
740
+ /**
741
+ * Mode-specific settings. Current modes take none.
742
+ */
527
743
  parameters?: {
528
744
  [key: string]: unknown;
529
745
  };
@@ -553,11 +769,11 @@ type SkillName = string;
553
769
  */
554
770
  type MemoryStoreName = string;
555
771
  /**
556
- * Sort order for named resources that expose created and modified timestamps.
772
+ * Field to sort by; prefix with - for descending order. Defaults to -created_at (newest first).
557
773
  */
558
774
  type ResourceListSort = 'name' | '-name' | '-updated_at' | 'updated_at' | '-created_at' | 'created_at';
559
775
  /**
560
- * Sort order for named resources that expose a created timestamp.
776
+ * Field to sort by; prefix with - for descending order. Defaults to -created_at (newest first).
561
777
  */
562
778
  type CreatedResourceListSort = 'name' | '-name' | '-created_at' | 'created_at';
563
779
  type AgentConfigErrorIssue = {
@@ -721,16 +937,16 @@ type ConfiguredModelId = string;
721
937
  type ConfiguredModelRevisionId = string;
722
938
  type ProjectModelGrantId = string;
723
939
  /**
724
- * Wire protocol the model endpoint speaks: openai-responses, openai-chat-completions, or anthropic-messages.
940
+ * Wire protocol the model endpoint speaks.
725
941
  */
726
942
  type ModelApiFormat = 'openai-responses' | 'openai-chat-completions' | 'anthropic-messages';
727
943
  /**
728
- * How the credential is sent: bearer_token, api_key_header, or sigv4 (AWS).
944
+ * How the credential is sent: as a bearer token, in the header named by auth_options.header_name, or signed with AWS SigV4.
729
945
  */
730
946
  type ModelProviderAuthKind = 'bearer_token' | 'api_key_header' | 'sigv4';
731
947
  type ModelProviderAuthKindResponse = string;
732
948
  /**
733
- * Provider-specific flavor of the API format: default, openrouter, or bedrock.
949
+ * Provider-specific variant of api_format. Use default unless the endpoint is OpenRouter or Bedrock.
734
950
  */
735
951
  type ModelProviderApiVariant = 'default' | 'openrouter' | 'bedrock';
736
952
  type ModelProviderApiVariantResponse = string;
@@ -776,8 +992,17 @@ type CreateModelProviderConfigRequest = {
776
992
  * Non-secret authentication settings. Use an empty object with bearer_token. With api_key_header, set {"header_name":"..."}; Anthropic Messages defaults to {"header_name":"x-api-key"}. With sigv4, set the AWS signing service and region.
777
993
  */
778
994
  auth_options?: {
995
+ /**
996
+ * Header that carries the API key when auth_kind is api_key_header.
997
+ */
779
998
  header_name?: string;
999
+ /**
1000
+ * AWS service to sign for when auth_kind is sigv4.
1001
+ */
780
1002
  service?: string;
1003
+ /**
1004
+ * AWS region to sign for when auth_kind is sigv4.
1005
+ */
781
1006
  region?: string;
782
1007
  };
783
1008
  credential_secret_id: SecretId;
@@ -819,8 +1044,17 @@ type UpdateModelProviderConfigRequest = {
819
1044
  * Non-secret authentication settings. Use an empty object with bearer_token. With api_key_header, set {"header_name":"..."}. With sigv4, set the AWS signing service and region.
820
1045
  */
821
1046
  auth_options?: {
1047
+ /**
1048
+ * Header that carries the API key when auth_kind is api_key_header.
1049
+ */
822
1050
  header_name?: string;
1051
+ /**
1052
+ * AWS service to sign for when auth_kind is sigv4.
1053
+ */
823
1054
  service?: string;
1055
+ /**
1056
+ * AWS region to sign for when auth_kind is sigv4.
1057
+ */
824
1058
  region?: string;
825
1059
  };
826
1060
  credential_secret_id?: SecretId;
@@ -838,28 +1072,70 @@ type UpdateModelProviderConfigRequest = {
838
1072
  };
839
1073
  };
840
1074
  type ModelProviderConfig = {
1075
+ /**
1076
+ * Identifies this provider config.
1077
+ */
841
1078
  id: ModelProviderConfigId;
1079
+ /**
1080
+ * Organization that owns this provider config.
1081
+ */
842
1082
  org_id: OrganizationId;
1083
+ /**
1084
+ * Whether the organization manages this provider or the Omnara installation provisions and manages it.
1085
+ */
843
1086
  management_kind: ManagementKind;
1087
+ /**
1088
+ * Name agent configs use to reference this provider as model.provider_config.
1089
+ */
844
1090
  name: ResourceName;
1091
+ /**
1092
+ * Wire protocol Omnara speaks to this provider.
1093
+ */
845
1094
  api_format: ModelApiFormat;
1095
+ /**
1096
+ * Provider-specific flavor of the API format.
1097
+ */
846
1098
  api_variant: ModelProviderApiVariantResponse;
847
1099
  /**
848
1100
  * Provider endpoint base URL.
849
1101
  */
850
1102
  base_url: string;
1103
+ /**
1104
+ * Path under base_url that model requests are sent to.
1105
+ */
851
1106
  endpoint_path: string;
1107
+ /**
1108
+ * Total deadline for one provider attempt, including reasoning and response streaming.
1109
+ */
852
1110
  request_timeout_ms: number;
1111
+ /**
1112
+ * Longest wait for response headers or more response data; heartbeats count as activity.
1113
+ */
853
1114
  idle_timeout_ms: number;
1115
+ /**
1116
+ * How Omnara sends the credential to the provider.
1117
+ */
854
1118
  auth_kind: ModelProviderAuthKindResponse;
855
1119
  /**
856
1120
  * Non-secret authentication settings for this provider config.
857
1121
  */
858
1122
  auth_options: {
1123
+ /**
1124
+ * Header that carries the API key when auth_kind is api_key_header.
1125
+ */
859
1126
  header_name?: string;
1127
+ /**
1128
+ * AWS service to sign for when auth_kind is sigv4.
1129
+ */
860
1130
  service?: string;
1131
+ /**
1132
+ * AWS region to sign for when auth_kind is sigv4.
1133
+ */
861
1134
  region?: string;
862
1135
  };
1136
+ /**
1137
+ * Secret holding the credential Omnara sends to the provider.
1138
+ */
863
1139
  credential_secret_id: SecretId;
864
1140
  /**
865
1141
  * Extra HTTP headers sent with every request to this provider.
@@ -873,7 +1149,13 @@ type ModelProviderConfig = {
873
1149
  secret_headers: {
874
1150
  [key: string]: SecretId;
875
1151
  };
1152
+ /**
1153
+ * When the provider config was created.
1154
+ */
876
1155
  created_at: Timestamp;
1156
+ /**
1157
+ * When the provider config was last changed.
1158
+ */
877
1159
  updated_at: Timestamp;
878
1160
  };
879
1161
  type CreateModelProviderConfigResponse = {
@@ -962,7 +1244,7 @@ type CreateConfiguredModelRequest = {
962
1244
  */
963
1245
  supports_reasoning?: boolean;
964
1246
  /**
965
- * Default reasoning effort to send for models/API formats that support effort-style reasoning controls. Requires supports_reasoning=true. When supported_reasoning_efforts is present, this value must be listed there.
1247
+ * Reasoning effort sent by default, such as low, medium, or high. Requires supports_reasoning; must be listed in supported_reasoning_efforts when that is set.
966
1248
  */
967
1249
  default_reasoning_effort?: string;
968
1250
  /**
@@ -1013,7 +1295,7 @@ type UpdateConfiguredModelRequest = {
1013
1295
  */
1014
1296
  supports_reasoning?: boolean;
1015
1297
  /**
1016
- * Default reasoning effort to send for models/API formats that support effort-style reasoning controls. Requires supports_reasoning=true. When supported_reasoning_efforts is present, this value must be listed there.
1298
+ * Reasoning effort sent by default, such as low, medium, or high. Requires supports_reasoning; must be listed in supported_reasoning_efforts when that is set.
1017
1299
  */
1018
1300
  default_reasoning_effort?: string;
1019
1301
  /**
@@ -1094,6 +1376,9 @@ type ConfiguredModelList = {
1094
1376
  * Grant a project access to a configured model. Optional fields can narrow the model's limits for this project; omitted fields inherit from the org-level configured model.
1095
1377
  */
1096
1378
  type CreateProjectModelGrantRequest = {
1379
+ /**
1380
+ * Configured model the project can use.
1381
+ */
1097
1382
  configured_model_id: ConfiguredModelId;
1098
1383
  /**
1099
1384
  * Optional project context budget for input and output tokens. Cannot exceed the configured model's budget. Triggers compaction when estimated input exceeds the remaining budget after output and safety reserves. The turn fails if compaction cannot make it fit.
@@ -1104,7 +1389,7 @@ type CreateProjectModelGrantRequest = {
1104
1389
  */
1105
1390
  max_output_tokens?: number;
1106
1391
  /**
1107
- * Optional project default per-request output-token cap.
1392
+ * Default output allowance per request for this project; agents can raise it up to max_output_tokens. Omit to inherit the configured model's.
1108
1393
  */
1109
1394
  default_max_output_tokens?: number;
1110
1395
  default_cache_retention?: ModelCacheRetention;
@@ -1117,11 +1402,11 @@ type CreateProjectModelGrantRequest = {
1117
1402
  */
1118
1403
  supports_reasoning?: boolean;
1119
1404
  /**
1120
- * Optional project default reasoning effort.
1405
+ * Reasoning effort this project uses by default, such as low or high. Omit to inherit the configured model's.
1121
1406
  */
1122
1407
  default_reasoning_effort?: string;
1123
1408
  /**
1124
- * Optional project subset of configured-model reasoning efforts. If this excludes the inherited default_reasoning_effort, set default_reasoning_effort on the grant too.
1409
+ * Reasoning efforts this project may use, limited to the configured model's. If this excludes the inherited default_reasoning_effort, set default_reasoning_effort too.
1125
1410
  */
1126
1411
  supported_reasoning_efforts?: Array<string>;
1127
1412
  /**
@@ -1146,9 +1431,12 @@ type UpdateProjectModelGrantRequest = {
1146
1431
  */
1147
1432
  max_output_tokens?: number | null;
1148
1433
  /**
1149
- * Project default per-request output-token cap.
1434
+ * Default output allowance per request for this project; agents can raise it up to max_output_tokens. Null inherits the configured model's.
1150
1435
  */
1151
1436
  default_max_output_tokens?: number | null;
1437
+ /**
1438
+ * Overrides the model's prompt caching for this project. Null inherits it.
1439
+ */
1152
1440
  default_cache_retention?: ModelCacheRetention | null;
1153
1441
  /**
1154
1442
  * Project-level tool-use gate. Can disable tools, but cannot enable tools when the configured model does not support them.
@@ -1159,19 +1447,19 @@ type UpdateProjectModelGrantRequest = {
1159
1447
  */
1160
1448
  supports_reasoning?: boolean | null;
1161
1449
  /**
1162
- * Project default reasoning effort.
1450
+ * Reasoning effort this project uses by default. Null inherits the configured model's.
1163
1451
  */
1164
1452
  default_reasoning_effort?: string | null;
1165
1453
  /**
1166
- * Project subset of configured-model reasoning efforts. If this excludes the inherited default_reasoning_effort, set default_reasoning_effort on the grant too.
1454
+ * Reasoning efforts this project may use, limited to the configured model's. If this excludes the inherited default_reasoning_effort, set default_reasoning_effort too.
1167
1455
  */
1168
1456
  supported_reasoning_efforts?: Array<string>;
1169
1457
  /**
1170
- * Project subset of configured-model input types.
1458
+ * Input types this project may send, such as text, image, or file; limited to the configured model's.
1171
1459
  */
1172
1460
  input_modalities?: Array<string>;
1173
1461
  /**
1174
- * Project subset of configured-model output types.
1462
+ * Output types this project may receive, limited to the configured model's.
1175
1463
  */
1176
1464
  output_modalities?: Array<string>;
1177
1465
  };
@@ -1396,10 +1684,25 @@ type SkillGrantCreateRequest = {
1396
1684
  target_project_id: ProjectId;
1397
1685
  };
1398
1686
  type SkillGrant = {
1687
+ /**
1688
+ * Identifies this grant; use it to revoke the project's access.
1689
+ */
1399
1690
  id: SkillGrantId;
1691
+ /**
1692
+ * Organization the grant and its skill belong to.
1693
+ */
1400
1694
  org_id: OrganizationId;
1695
+ /**
1696
+ * Skill shared by this grant.
1697
+ */
1401
1698
  skill_id: SkillId;
1699
+ /**
1700
+ * Project that can attach the skill through this grant.
1701
+ */
1402
1702
  target_project_id: ProjectId;
1703
+ /**
1704
+ * When the skill was granted to the project.
1705
+ */
1403
1706
  created_at: Timestamp;
1404
1707
  };
1405
1708
  type SkillGrantListItem = {
@@ -1614,9 +1917,12 @@ type ResolvedAgentConfigTool = {
1614
1917
  * An agent config to compile. The source, YAML or JSON, as text or as a JSON object, is stored exactly as sent, so comments and formatting survive. Configs whose sources compile to the same definition share it, however their sources are formatted.
1615
1918
  */
1616
1919
  type CreateAgentConfigRequest = {
1920
+ /**
1921
+ * Config to compile: YAML or JSON text, or a JSON object when source_format is json.
1922
+ */
1617
1923
  source: AgentConfigSourceInput;
1618
1924
  /**
1619
- * Format of source: yaml or json.
1925
+ * Encoding of source.
1620
1926
  */
1621
1927
  source_format: 'yaml' | 'json';
1622
1928
  };
@@ -1628,44 +1934,92 @@ type AgentConfigSourceInput = string | AgentConfigDefinition;
1628
1934
  * Replaces a live agent's config. expected_current_config_id makes the change conditional on the agent still running that config, so concurrent editors get a conflict instead of silently overwriting each other.
1629
1935
  */
1630
1936
  type UpdateAgentConfigRequest = {
1937
+ /**
1938
+ * Config to compile: YAML or JSON text, or a JSON object when source_format is json.
1939
+ */
1631
1940
  source: AgentConfigSourceInput;
1632
1941
  /**
1633
- * Format of source: yaml or json.
1942
+ * Encoding of source.
1634
1943
  */
1635
1944
  source_format: 'yaml' | 'json';
1636
1945
  expected_current_config_id?: AgentConfigId;
1637
1946
  };
1638
1947
  type ToolPermissionSelection = {
1948
+ /**
1949
+ * Permission mode applied by default.
1950
+ */
1639
1951
  mode: string;
1952
+ /**
1953
+ * Parameters for the default mode.
1954
+ */
1640
1955
  parameters: {
1641
1956
  [key: string]: unknown;
1642
1957
  };
1643
1958
  };
1644
1959
  type ToolPermissionMode = {
1960
+ /**
1961
+ * Mode name to set as permission.mode in an agent config.
1962
+ */
1645
1963
  name: string;
1964
+ /**
1965
+ * Display label for the mode.
1966
+ */
1646
1967
  label: string;
1968
+ /**
1969
+ * What the mode does when a tool is called.
1970
+ */
1647
1971
  description: string;
1972
+ /**
1973
+ * JSON Schema for the mode's permission.parameters.
1974
+ */
1648
1975
  parameters_schema: {
1649
1976
  [key: string]: unknown;
1650
1977
  };
1651
1978
  };
1652
1979
  type ToolPermissionProfile = {
1980
+ /**
1981
+ * Permission these tools get when a config does not set one.
1982
+ */
1653
1983
  default_permission: ToolPermissionSelection;
1984
+ /**
1985
+ * Permission modes a config can set for these tools.
1986
+ */
1654
1987
  permission_modes: Array<ToolPermissionMode>;
1655
1988
  };
1656
1989
  type ToolCatalogEntry = {
1990
+ /**
1991
+ * Name to list under tools in an agent config to enable this tool.
1992
+ */
1657
1993
  name: string;
1994
+ /**
1995
+ * What the tool does.
1996
+ */
1658
1997
  description: string;
1659
1998
  /**
1660
1999
  * Whether this tool supports implicit inclusion based on config resources or integration context, even when explicitly configured.
1661
2000
  */
1662
2001
  implicit?: boolean;
2002
+ /**
2003
+ * Permission the tool gets when a config does not set one.
2004
+ */
1663
2005
  default_permission: ToolPermissionSelection;
2006
+ /**
2007
+ * Permission modes a config can set for this tool.
2008
+ */
1664
2009
  permission_modes: Array<ToolPermissionMode>;
1665
2010
  };
1666
2011
  type ToolCatalog = {
2012
+ /**
2013
+ * Built-in tools available in this deployment.
2014
+ */
1667
2015
  built_in_tools: Array<ToolCatalogEntry>;
2016
+ /**
2017
+ * Default permission and allowed modes for custom tools.
2018
+ */
1668
2019
  custom_tool_permissions: ToolPermissionProfile;
2020
+ /**
2021
+ * Default permission and allowed modes for MCP tools.
2022
+ */
1669
2023
  mcp_tool_permissions: ToolPermissionProfile;
1670
2024
  };
1671
2025
  type McpRegistryHeader = {
@@ -2103,16 +2457,37 @@ type ListAgentProfilesResponse = {
2103
2457
  next_cursor: string | null;
2104
2458
  };
2105
2459
  type AgentCronTriggerTarget = {
2460
+ /**
2461
+ * agent: send each message to an existing agent.
2462
+ */
2106
2463
  type: 'agent';
2464
+ /**
2465
+ * Agent that receives each message.
2466
+ */
2107
2467
  agent_id: AgentId;
2468
+ /**
2469
+ * How each message is delivered: queued (default) or steering.
2470
+ */
2108
2471
  delivery_mode?: CronTriggerDeliveryMode;
2109
2472
  };
2110
2473
  type AgentProfileCronTriggerTarget = {
2474
+ /**
2475
+ * profile: launch a new agent on each run.
2476
+ */
2111
2477
  type: 'profile';
2478
+ /**
2479
+ * Profile to launch a new agent from on each run.
2480
+ */
2112
2481
  agent_profile_id: AgentProfileId;
2113
2482
  };
2114
2483
  type IntegrationCronTriggerTarget = {
2484
+ /**
2485
+ * integration: hand each run to an integration.
2486
+ */
2115
2487
  type: 'integration';
2488
+ /**
2489
+ * Integration that handles each run.
2490
+ */
2116
2491
  integration_id: IntegrationId;
2117
2492
  /**
2118
2493
  * Settings validated by the target integration's published schedule input schema. Each accepted occurrence retains its own copy. Integration resource references are resolved when the integration handles the occurrence.
@@ -2239,6 +2614,9 @@ type CreateAgentRequest = ({
2239
2614
  } | {
2240
2615
  config_source: CreateAgentConfigRequest;
2241
2616
  }) & {
2617
+ /**
2618
+ * Agent profile to launch. Runs its current config unless config or config_source is set.
2619
+ */
2242
2620
  profile?: AgentProfileId;
2243
2621
  config?: AgentConfigId;
2244
2622
  config_source?: CreateAgentConfigRequest;
@@ -2272,6 +2650,9 @@ type CreateAgentRequest = ({
2272
2650
  * Initial queued text input, committed atomically with the agent and any derived config. Mutually exclusive with message. Initial inline media is not supported; upload it through the agent input endpoint after launch.
2273
2651
  */
2274
2652
  type AgentLaunchInitialInput = {
2653
+ /**
2654
+ * Text blocks that make up the agent's first message.
2655
+ */
2275
2656
  content_blocks: Array<TextContentBlock>;
2276
2657
  /**
2277
2658
  * Optional external actor for API key authentication. User-authenticated requests must omit this field. Without it, the authenticated user or API key is the actor.
@@ -2406,25 +2787,46 @@ type ModelStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'refusal' | 'con
2406
2787
  */
2407
2788
  type ModelOutputStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'refusal' | 'content_filter' | 'error';
2408
2789
  /**
2409
- * Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters. Keys beginning with `omnara_` are reserved for Omnara and may affect product behavior; use them only when intentionally invoking Omnara-defined behavior.
2790
+ * Arbitrary key-value labels. Keys beginning with `omnara_` are reserved for Omnara and may affect product behavior; use them only when intentionally invoking Omnara-defined behavior.
2410
2791
  */
2411
2792
  type ContentBlockMetadata = Metadata;
2412
2793
  type TextContentBlock = {
2794
+ /**
2795
+ * text: a plain-text block.
2796
+ */
2413
2797
  type: 'text';
2798
+ /**
2799
+ * Block text: the message in agent inputs, or text from the model or a tool in events.
2800
+ */
2414
2801
  text: string;
2802
+ /**
2803
+ * Key-value metadata. omnara_ keys are reserved.
2804
+ */
2415
2805
  metadata?: ContentBlockMetadata;
2416
2806
  };
2417
2807
  /**
2418
2808
  * Files that pass validation are stored as artifacts. Model input always includes the artifact ID, whether or not the file contents can be sent directly. Text media must contain valid UTF-8 and is sent as text. Images and PDFs are sent directly when supported by the configured provider and model; unsupported combinations are rejected. Other binary documents are sent directly only to OpenAI Responses models with file input support. Chat Completions and Anthropic Messages receive the artifact ID and the filename, if provided, instead of the contents of those documents.
2419
2809
  */
2420
2810
  type InlineMediaContentBlock = {
2811
+ /**
2812
+ * media: a base64-encoded file in data.
2813
+ */
2421
2814
  type: 'media';
2815
+ /**
2816
+ * MIME type of the file in data.
2817
+ */
2422
2818
  media_type: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/csv' | 'text/tab-separated-values' | 'text/x-iif' | 'application/msword' | 'application/rtf' | 'application/vnd.oasis.opendocument.text' | 'application/vnd.apple.pages' | 'application/vnd.apple.keynote' | 'application/vnd.apple.iwork' | 'application/vnd.ms-powerpoint' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
2819
+ /**
2820
+ * Filename saved with the stored file and shown to models that can't read the file directly.
2821
+ */
2423
2822
  filename?: string;
2424
2823
  /**
2425
2824
  * Base64-encoded file bytes. For text media types, the decoded bytes must be valid UTF-8.
2426
2825
  */
2427
2826
  data: string;
2827
+ /**
2828
+ * Key-value metadata. omnara_ keys are reserved.
2829
+ */
2428
2830
  metadata?: ContentBlockMetadata;
2429
2831
  };
2430
2832
  type MediaRefContentBlock = {
@@ -2546,12 +2948,33 @@ type AgentMachineBinding = {
2546
2948
  * The machine's most recent daemon-reported failure. A single slot, overwritten by newer reports. Runtime crash reports remain as historical diagnostics; recovery may clear other failure stages.
2547
2949
  */
2548
2950
  type MachineFailureReport = {
2951
+ /**
2952
+ * Setup or daemon step that failed.
2953
+ */
2549
2954
  stage: 'startup_script' | 'daemon_install' | 'daemon_update' | 'daemon_runtime' | 'daemon_uninstall' | 'daemon_uninstalled';
2955
+ /**
2956
+ * Exit status of the failed startup script or daemon install; omitted for other stages.
2957
+ */
2550
2958
  exit_status?: number;
2959
+ /**
2960
+ * End of the failed step's output, for diagnosis.
2961
+ */
2551
2962
  output_tail: string;
2963
+ /**
2964
+ * True when earlier output was dropped or output capture failed.
2965
+ */
2552
2966
  output_truncated: boolean;
2967
+ /**
2968
+ * Daemon version that was running when a daemon update failed.
2969
+ */
2553
2970
  daemon_version?: string;
2971
+ /**
2972
+ * Version the daemon was trying to update to when the update failed.
2973
+ */
2554
2974
  target_version?: string;
2975
+ /**
2976
+ * When the failure was reported.
2977
+ */
2555
2978
  reported_at: Timestamp;
2556
2979
  };
2557
2980
  type LaunchAgentResponse = {
@@ -2576,7 +2999,7 @@ type ToolInput = {
2576
2999
  [key: string]: unknown;
2577
3000
  };
2578
3001
  /**
2579
- * Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters.
3002
+ * Arbitrary key-value labels stored with the resource.
2580
3003
  */
2581
3004
  type Metadata = {
2582
3005
  [key: string]: string;
@@ -2592,6 +3015,9 @@ type CreateAgentInputRequest = {
2592
3015
  * At most 20 inline media blocks per submission, each holding up to 10 MiB of decoded media and up to 24 MiB decoded across the submission. Non-media blocks may hold up to 1 MiB combined. The whole request body is capped at 48 MiB.
2593
3016
  */
2594
3017
  content_blocks: Array<CreateAgentInputContentBlock>;
3018
+ /**
3019
+ * queued (default) waits until the agent is free; steering reaches it at its next model call.
3020
+ */
2595
3021
  delivery_mode?: CreateAgentInputDeliveryMode;
2596
3022
  /**
2597
3023
  * Only valid when delivery_mode is steering. When true, atomically cancels open interactions associated with the current turn's unfinished tool calls before creating the steering input. Their parent tool calls complete as canceled; the turn, runtime, and unrelated tool calls are preserved.
@@ -3091,9 +3517,12 @@ type InteractionForm = {
3091
3517
  questions: Array<InteractionFormQuestion>;
3092
3518
  };
3093
3519
  type InteractionAnswer = {
3520
+ /**
3521
+ * Zero-based indices of the chosen options. Pick one unless the question allows multiple.
3522
+ */
3094
3523
  option_indices: Array<number>;
3095
3524
  /**
3096
- * Optional companion text when the selected option allows it.
3525
+ * Free text sent with an option whose allows_text is true.
3097
3526
  */
3098
3527
  text?: string;
3099
3528
  };
@@ -3106,6 +3535,9 @@ type InteractionResolution = {
3106
3535
  type AgentInteractionKind = 'permission' | 'question';
3107
3536
  type AgentInteractionState = 'open' | 'resolved' | 'canceled';
3108
3537
  type ResolveAgentInteractionRequest = {
3538
+ /**
3539
+ * One answer per question, in order.
3540
+ */
3109
3541
  answers: Array<InteractionAnswer>;
3110
3542
  /**
3111
3543
  * External actor to attribute to the generated interaction_response agent input, upserted by (provider_tenant_id, provider_user_id) atomically with the resolution; a rejected request writes no actor. Only allowed for non-user principals; requests authenticated as a user must omit it and are attributed to the user's omnara actor. When a non-user request omits it, the generated input has no actor attribution.
@@ -3194,9 +3626,21 @@ type Actor = {
3194
3626
  * Identity and attributes of an external actor. Actors are upserted by (provider_tenant_id, provider_user_id) with the external provider. Omitted attributes keep their stored values; provided attributes are overwritten, including empty values. omnara actors are implicit and hosted integrations own their own actor identities.
3195
3627
  */
3196
3628
  type ExternalActorParams = {
3629
+ /**
3630
+ * Your tenant or namespace for the user. With provider_user_id, identifies the actor.
3631
+ */
3197
3632
  provider_tenant_id?: string;
3633
+ /**
3634
+ * The user's ID in your system. With provider_tenant_id, identifies the actor.
3635
+ */
3198
3636
  provider_user_id: string;
3637
+ /**
3638
+ * Display name for the actor.
3639
+ */
3199
3640
  display_name?: string;
3641
+ /**
3642
+ * Key-value attributes for the actor. Replaces stored metadata when sent.
3643
+ */
3200
3644
  metadata?: Metadata;
3201
3645
  };
3202
3646
  type ListActorsResponse = {
@@ -3208,13 +3652,25 @@ type ListAgentInteractionsResponse = {
3208
3652
  next_cursor: string | null;
3209
3653
  };
3210
3654
  type OrgSecretOwnerInput = {
3655
+ /**
3656
+ * org: owned by the organization. Projects need a grant to use it.
3657
+ */
3211
3658
  kind: 'org';
3212
3659
  };
3213
3660
  type ProjectSecretOwnerInput = {
3661
+ /**
3662
+ * project: owned by one project.
3663
+ */
3214
3664
  kind: 'project';
3665
+ /**
3666
+ * Owning project.
3667
+ */
3215
3668
  project_id: ProjectId;
3216
3669
  };
3217
3670
  type UserSecretOwnerInput = {
3671
+ /**
3672
+ * user: owned by the calling user, for personal credentials. Projects need a grant to use it.
3673
+ */
3218
3674
  kind: 'user';
3219
3675
  };
3220
3676
  /**
@@ -3228,14 +3684,29 @@ type SecretOwnerInput = ({
3228
3684
  kind: 'user';
3229
3685
  } & UserSecretOwnerInput);
3230
3686
  type OrgSecretOwner = {
3687
+ /**
3688
+ * org: the organization owns the secret.
3689
+ */
3231
3690
  kind: 'org';
3232
3691
  };
3233
3692
  type ProjectSecretOwner = {
3693
+ /**
3694
+ * project: a single project owns the secret.
3695
+ */
3234
3696
  kind: 'project';
3697
+ /**
3698
+ * Project that owns the secret.
3699
+ */
3235
3700
  project_id: ProjectId;
3236
3701
  };
3237
3702
  type UserSecretOwner = {
3703
+ /**
3704
+ * user: a user owns the secret.
3705
+ */
3238
3706
  kind: 'user';
3707
+ /**
3708
+ * User who owns the secret.
3709
+ */
3239
3710
  user_id: UserId;
3240
3711
  };
3241
3712
  type SecretOwner = ({
@@ -3246,47 +3717,113 @@ type SecretOwner = ({
3246
3717
  kind: 'user';
3247
3718
  } & UserSecretOwner);
3248
3719
  type GenericSecretMaterial = {
3720
+ /**
3721
+ * generic: a single value, such as an API key.
3722
+ */
3249
3723
  kind: 'generic';
3724
+ /**
3725
+ * The secret value, up to 64 KiB.
3726
+ */
3250
3727
  value: string;
3251
3728
  };
3252
3729
  type OAuthRefreshSecretMaterial = {
3730
+ /**
3731
+ * Refresh token exchanged at token_endpoint for new access tokens.
3732
+ */
3253
3733
  refresh_token: string;
3254
3734
  /**
3255
- * Must use HTTPS, except that HTTP is allowed for loopback hosts during local development.
3735
+ * OAuth token endpoint used to refresh the access token. Must be HTTPS, except for loopback hosts in local development.
3256
3736
  */
3257
3737
  token_endpoint: string;
3738
+ /**
3739
+ * OAuth client ID.
3740
+ */
3258
3741
  client_id: string;
3742
+ /**
3743
+ * OAuth client secret sent with refresh requests. Omit if the client has none.
3744
+ */
3259
3745
  client_secret?: string;
3746
+ /**
3747
+ * Resource indicator sent with refresh requests.
3748
+ */
3260
3749
  resource: string;
3261
3750
  };
3262
3751
  type OAuthTokenSetSecretMaterial = {
3752
+ /**
3753
+ * oauth_token_set: OAuth tokens for MCP servers that use oauth auth.
3754
+ */
3263
3755
  kind: 'oauth_token_set';
3756
+ /**
3757
+ * Access token sent to the MCP server; replaced on each refresh.
3758
+ */
3264
3759
  access_token: string;
3760
+ /**
3761
+ * Seconds until the access token expires. Omit if it doesn't expire.
3762
+ */
3265
3763
  access_token_expires_in_seconds?: number;
3764
+ /**
3765
+ * Refresh material. Without it, the token can't be renewed once it expires.
3766
+ */
3266
3767
  refresh?: OAuthRefreshSecretMaterial;
3768
+ /**
3769
+ * OpenID Connect ID token, if one was issued.
3770
+ */
3267
3771
  id_token?: string;
3772
+ /**
3773
+ * URL of the MCP server the tokens were issued for.
3774
+ */
3268
3775
  mcp_url?: string;
3776
+ /**
3777
+ * Granted scopes, space-separated.
3778
+ */
3269
3779
  scopes?: string;
3780
+ /**
3781
+ * Token type, such as Bearer.
3782
+ */
3270
3783
  token_type?: string;
3271
3784
  };
3272
3785
  type AwsCredentialsSecretMaterial = {
3786
+ /**
3787
+ * aws_credentials: AWS access keys used to sign requests with SigV4.
3788
+ */
3273
3789
  kind: 'aws_credentials';
3790
+ /**
3791
+ * AWS access key ID.
3792
+ */
3274
3793
  access_key_id: string;
3794
+ /**
3795
+ * AWS secret access key.
3796
+ */
3275
3797
  secret_access_key: string;
3798
+ /**
3799
+ * Session token for temporary credentials. Not refreshed automatically.
3800
+ */
3276
3801
  session_token?: string;
3802
+ /**
3803
+ * IAM role to assume through STS before signing.
3804
+ */
3277
3805
  role_arn?: string;
3278
3806
  /**
3279
- * Requires role_arn.
3807
+ * External ID sent to STS when assuming role_arn.
3280
3808
  */
3281
3809
  external_id?: string;
3282
3810
  };
3283
3811
  type GitHubAppCredentialsSecretMaterial = {
3812
+ /**
3813
+ * github_app_credentials: a GitHub App's ID, private key, and webhook secret.
3814
+ */
3284
3815
  kind: 'github_app_credentials';
3816
+ /**
3817
+ * GitHub App ID, not the installation ID.
3818
+ */
3285
3819
  app_id: string;
3286
3820
  /**
3287
3821
  * Unencrypted RSA private key in PEM format. Stored encrypted.
3288
3822
  */
3289
3823
  private_key: string;
3824
+ /**
3825
+ * The App's webhook secret, used to verify webhook signatures.
3826
+ */
3290
3827
  webhook_secret: string;
3291
3828
  };
3292
3829
  /**
@@ -3319,16 +3856,49 @@ type SecretGrantCreateRequest = {
3319
3856
  };
3320
3857
  type SecretKind = 'generic' | 'oauth_token_set' | 'slack_app_credentials' | 'aws_credentials' | 'github_app_credentials';
3321
3858
  type Secret = {
3859
+ /**
3860
+ * Identifies the secret; other resources reference it by this ID instead of storing the value.
3861
+ */
3322
3862
  id: SecretId;
3863
+ /**
3864
+ * Organization the secret belongs to.
3865
+ */
3323
3866
  org_id: OrganizationId;
3867
+ /**
3868
+ * Whether the organization manages this secret or the Omnara installation provisions and manages it.
3869
+ */
3324
3870
  management_kind: ManagementKind;
3871
+ /**
3872
+ * Who owns the secret; a project can use it without a grant only if the project owns it.
3873
+ */
3325
3874
  owner: SecretOwner;
3875
+ /**
3876
+ * Display name of the secret.
3877
+ */
3326
3878
  name: ResourceName;
3879
+ /**
3880
+ * What type of credential the secret holds, which determines its payload fields.
3881
+ */
3327
3882
  kind: SecretKind;
3883
+ /**
3884
+ * Caller-supplied key-value labels on the secret.
3885
+ */
3328
3886
  metadata: Metadata;
3887
+ /**
3888
+ * Version of the value currently in use; each rotation increments it.
3889
+ */
3329
3890
  current_version_number: number;
3891
+ /**
3892
+ * Names of the fields stored in the current value, such as value or access_token; values are never returned.
3893
+ */
3330
3894
  payload_keys: Array<string>;
3895
+ /**
3896
+ * When the secret was created.
3897
+ */
3331
3898
  created_at: Timestamp;
3899
+ /**
3900
+ * When the secret's name, metadata, or current version last changed.
3901
+ */
3332
3902
  updated_at: Timestamp;
3333
3903
  };
3334
3904
  type ListSecretsResponse = {
@@ -3358,10 +3928,25 @@ type ListProjectSecretAccessesResponse = {
3358
3928
  next_cursor: string | null;
3359
3929
  };
3360
3930
  type SecretGrant = {
3931
+ /**
3932
+ * Identifies this grant; use it to revoke the project's access.
3933
+ */
3361
3934
  id: SecretGrantId;
3935
+ /**
3936
+ * Organization the grant and its secret belong to.
3937
+ */
3362
3938
  org_id: OrganizationId;
3939
+ /**
3940
+ * Secret shared by this grant.
3941
+ */
3363
3942
  secret_id: SecretId;
3943
+ /**
3944
+ * Project that can use the secret through this grant.
3945
+ */
3364
3946
  target_project_id: ProjectId;
3947
+ /**
3948
+ * When the secret was granted to the project.
3949
+ */
3365
3950
  created_at: Timestamp;
3366
3951
  };
3367
3952
  type SecretGrantListItem = {
@@ -3376,20 +3961,53 @@ type CreateOrganizationRequest = {
3376
3961
  name: ResourceName;
3377
3962
  };
3378
3963
  type CreateOrganizationResponse = {
3964
+ /**
3965
+ * The newly created organization.
3966
+ */
3379
3967
  org: Organization;
3968
+ /**
3969
+ * Default project created along with the organization.
3970
+ */
3380
3971
  project: Project;
3972
+ /**
3973
+ * The caller's owner membership in the new organization.
3974
+ */
3381
3975
  membership: OrganizationMembership;
3382
3976
  };
3383
3977
  type Organization = {
3978
+ /**
3979
+ * Identifies the organization.
3980
+ */
3384
3981
  id: OrganizationId;
3982
+ /**
3983
+ * Display name of the organization.
3984
+ */
3385
3985
  name: ResourceName;
3986
+ /**
3987
+ * When the organization was created.
3988
+ */
3386
3989
  created_at: Timestamp;
3990
+ /**
3991
+ * When the organization record was last changed.
3992
+ */
3387
3993
  updated_at: Timestamp;
3388
3994
  };
3389
3995
  type OrganizationMembership = {
3996
+ /**
3997
+ * Organization the user belongs to.
3998
+ */
3390
3999
  org_id: OrganizationId;
4000
+ /**
4001
+ * User who holds this membership.
4002
+ */
3391
4003
  user_id: UserId;
4004
+ /**
4005
+ * The user's organization role, which sets what they can do in the org.
4006
+ */
3392
4007
  role: string;
4008
+ /**
4009
+ * When the user joined the organization; role changes do not update it.
4010
+ */
3393
4011
  created_at: Timestamp;
3394
4012
  };
3395
4013
  type OrgInvitation = {
@@ -3533,10 +4151,25 @@ type MachinePoolConnectionCheckError = {
3533
4151
  details?: string;
3534
4152
  };
3535
4153
  type CreateMachinePoolRequestBase = {
4154
+ /**
4155
+ * Pool name, unique in the organization. Agent configs reference it as machine_pool_name.
4156
+ */
3536
4157
  name: ResourceName;
4158
+ /**
4159
+ * Free-form description of the pool.
4160
+ */
3537
4161
  description?: string;
4162
+ /**
4163
+ * Sandbox provider. Determines which size and limit fields are required.
4164
+ */
3538
4165
  provider: string;
4166
+ /**
4167
+ * Default vCPUs per machine, between min_machine_cpu and max_machine_cpu.
4168
+ */
3539
4169
  default_machine_cpu?: number;
4170
+ /**
4171
+ * Default memory per machine in MB, between min_machine_memory_mb and max_machine_memory_mb.
4172
+ */
3540
4173
  default_machine_memory_mb?: number;
3541
4174
  /**
3542
4175
  * Default environment for pool machines. A machine's environment, including resolved secret_env values, is applied to the provider machine at provisioning, so the provider_options startup_script and the daemon run with it, and is resolved again for each process at launch.
@@ -3550,35 +4183,71 @@ type CreateMachinePoolRequestBase = {
3550
4183
  default_machine_secret_env?: {
3551
4184
  [key: string]: SecretId;
3552
4185
  };
4186
+ /**
4187
+ * Provider options for new machines, such as image, region, or startup_script. Keys depend on the provider.
4188
+ */
3553
4189
  default_machine_provider_options: {
3554
4190
  [key: string]: unknown;
3555
4191
  };
4192
+ /**
4193
+ * Default working directory for processes.
4194
+ */
3556
4195
  default_cwd?: string;
4196
+ /**
4197
+ * Pool-wide provider settings, such as a workspace or domain, and allowlists for overrides. Keys depend on the provider.
4198
+ */
3557
4199
  provider_config?: {
3558
4200
  [key: string]: unknown;
3559
4201
  };
4202
+ /**
4203
+ * Org-owned generic secret holding the provider API key.
4204
+ */
3560
4205
  provider_auth_secret_id: SecretId;
3561
4206
  /**
3562
- * Whether Omnara should delete a pool machine when its provider remains running after its daemon becomes inactive. Defaults to false when omitted.
4207
+ * When true, Omnara deletes pool machines that keep running at the provider after their daemon goes inactive. Defaults to false.
3563
4208
  */
3564
4209
  runtime_protection_enabled?: boolean;
4210
+ /**
4211
+ * Most live machines across all projects. 0 blocks new machines.
4212
+ */
3565
4213
  max_total_machines: number;
4214
+ /**
4215
+ * Most vCPUs across live machines.
4216
+ */
3566
4217
  max_total_cpu?: number;
4218
+ /**
4219
+ * Most memory in MB across live machines.
4220
+ */
3567
4221
  max_total_memory_mb?: number;
4222
+ /**
4223
+ * Fewest vCPUs per machine. 0 means no minimum.
4224
+ */
3568
4225
  min_machine_cpu?: number;
4226
+ /**
4227
+ * Least memory per machine in MB. 0 means no minimum.
4228
+ */
3569
4229
  min_machine_memory_mb?: number;
4230
+ /**
4231
+ * Most vCPUs per machine.
4232
+ */
3570
4233
  max_machine_cpu?: number;
4234
+ /**
4235
+ * Most memory per machine in MB.
4236
+ */
3571
4237
  max_machine_memory_mb?: number;
3572
4238
  /**
3573
4239
  * Idle minutes before deleting a machine from this pool. Omit to leave the pool default unset; a grant or agent source may still override it.
3574
4240
  */
3575
4241
  delete_after_idle_minutes?: number;
4242
+ /**
4243
+ * Key-value metadata copied to the pool's machines.
4244
+ */
3576
4245
  metadata?: MachineMetadata;
3577
4246
  };
3578
4247
  type UpdateMachinePoolRequest = {
3579
4248
  name?: ResourceName;
3580
4249
  /**
3581
- * Optional description of the pool.
4250
+ * Free-form description of the pool.
3582
4251
  */
3583
4252
  description?: string;
3584
4253
  /**
@@ -3602,7 +4271,7 @@ type UpdateMachinePoolRequest = {
3602
4271
  [key: string]: SecretId;
3603
4272
  };
3604
4273
  /**
3605
- * Provider-specific options applied to new machines in the pool.
4274
+ * Provider options for new machines, such as image, region, or startup_script. Keys depend on the provider.
3606
4275
  */
3607
4276
  default_machine_provider_options?: {
3608
4277
  [key: string]: unknown;
@@ -3612,14 +4281,14 @@ type UpdateMachinePoolRequest = {
3612
4281
  */
3613
4282
  default_cwd?: string;
3614
4283
  /**
3615
- * Provider-specific settings for the pool.
4284
+ * Pool-wide provider settings, such as a workspace or domain, and allowlists for overrides. Keys depend on the provider.
3616
4285
  */
3617
4286
  provider_config?: {
3618
4287
  [key: string]: unknown;
3619
4288
  };
3620
4289
  provider_auth_secret_id?: SecretId;
3621
4290
  /**
3622
- * Whether Omnara should delete a pool machine when its provider remains running after its daemon becomes inactive.
4291
+ * When true, Omnara deletes pool machines that keep running at the provider after their daemon goes inactive.
3623
4292
  */
3624
4293
  runtime_protection_enabled?: boolean;
3625
4294
  /**
@@ -3723,33 +4392,105 @@ type MachineConnectionState = 'online' | 'asleep' | 'offline';
3723
4392
  type MachineAccessSourceKind = 'org_role' | 'project_machine_grant';
3724
4393
  type ProjectMachineGrantSourceKind = 'explicit' | 'pool';
3725
4394
  type Machine = {
4395
+ /**
4396
+ * Identifies the machine.
4397
+ */
3726
4398
  id: MachineId;
4399
+ /**
4400
+ * Organization that owns the machine.
4401
+ */
3727
4402
  org_id: OrganizationId;
4403
+ /**
4404
+ * Whether the machine is a bring-your-own computer or was created from a machine pool.
4405
+ */
3728
4406
  source_kind: MachineSourceKind;
4407
+ /**
4408
+ * Pool the machine was created from; null for BYO machines.
4409
+ */
3729
4410
  machine_pool_id?: MachinePoolId | null;
4411
+ /**
4412
+ * Machine name; agent configs reference a BYO machine by this as machine_name.
4413
+ */
3730
4414
  display_name: ResourceName;
4415
+ /**
4416
+ * Free-form note about the machine; empty if none was set.
4417
+ */
3731
4418
  description: string;
4419
+ /**
4420
+ * Sandbox provider that hosts a pool machine; byo for bring-your-own machines.
4421
+ */
3732
4422
  provider: string;
4423
+ /**
4424
+ * Where the machine is in provisioning or deletion, independent of whether its daemon is connected.
4425
+ */
3733
4426
  lifecycle_state: MachineLifecycleState;
4427
+ /**
4428
+ * Whether the machine's daemon is connected now; asleep means suspended but able to be woken.
4429
+ */
3734
4430
  connection_state: MachineConnectionState;
4431
+ /**
4432
+ * Why the machine's latest daemon session ended, such as daemon_lease_expired.
4433
+ */
3735
4434
  connection_state_reason?: string;
4435
+ /**
4436
+ * When the daemon last registered or sent a heartbeat; null if it has never connected.
4437
+ */
3736
4438
  last_observed_at: Timestamp | null;
4439
+ /**
4440
+ * Default working directory for processes started on the machine.
4441
+ */
3737
4442
  cwd: string;
4443
+ /**
4444
+ * Environment variables set for every process started on the machine.
4445
+ */
3738
4446
  env: {
3739
4447
  [key: string]: string;
3740
4448
  };
4449
+ /**
4450
+ * Environment variable names mapped to secrets whose values are injected when processes start.
4451
+ */
3741
4452
  secret_env: {
3742
4453
  [key: string]: SecretId;
3743
4454
  };
4455
+ /**
4456
+ * Machine-readable reason for the latest lifecycle change, such as idle_timeout; empty when none.
4457
+ */
3744
4458
  lifecycle_reason_code: string;
4459
+ /**
4460
+ * Human-readable detail for lifecycle_reason_code; empty when none.
4461
+ */
3745
4462
  lifecycle_reason_message: string;
4463
+ /**
4464
+ * Latest setup or daemon failure reported from the machine; omitted when none is recorded.
4465
+ */
3746
4466
  failure_report?: MachineFailureReport;
4467
+ /**
4468
+ * When Omnara next works on provisioning or deleting the machine; null when nothing is scheduled.
4469
+ */
3747
4470
  next_reconcile_after: Timestamp | null;
4471
+ /**
4472
+ * Number of times Omnara has tried to provision this machine.
4473
+ */
3748
4474
  provision_attempts: number;
4475
+ /**
4476
+ * Number of times Omnara has tried to delete this machine.
4477
+ */
3749
4478
  delete_attempts: number;
4479
+ /**
4480
+ * Key-value metadata attached to the machine.
4481
+ */
3750
4482
  metadata: Metadata;
4483
+ /**
4484
+ * When the machine finished deleting; null while it still exists.
4485
+ */
3751
4486
  deleted_at: Timestamp | null;
4487
+ /**
4488
+ * When the machine record was created.
4489
+ */
3752
4490
  created_at: Timestamp;
4491
+ /**
4492
+ * When the machine record last changed.
4493
+ */
3753
4494
  updated_at: Timestamp;
3754
4495
  };
3755
4496
  type CreateMachineRequest = {
@@ -3767,7 +4508,7 @@ type CreateMachineRequest = {
3767
4508
  type ConnectByoMachineRequest = {
3768
4509
  display_name: ResourceName;
3769
4510
  /**
3770
- * Optional description of the machine.
4511
+ * Free-form description stored with the machine.
3771
4512
  */
3772
4513
  description?: string;
3773
4514
  /**
@@ -3775,20 +4516,20 @@ type ConnectByoMachineRequest = {
3775
4516
  */
3776
4517
  cwd?: string;
3777
4518
  /**
3778
- * Environment variables set for processes started on the machine.
4519
+ * Environment variables for processes started on the machine.
3779
4520
  */
3780
4521
  env?: {
3781
4522
  [key: string]: string;
3782
4523
  };
3783
4524
  /**
3784
- * Environment variable names mapped to secret IDs (sec_...) whose values are set for processes started on the machine.
4525
+ * Environment variables set from secrets, keyed by variable name, for processes started on the machine.
3785
4526
  */
3786
4527
  secret_env?: {
3787
4528
  [key: string]: SecretId;
3788
4529
  };
3789
4530
  metadata?: MachineMetadata;
3790
4531
  /**
3791
- * Projects to grant the machine to in the same call (up to 100).
4532
+ * Projects to grant the machine to in the same call.
3792
4533
  */
3793
4534
  project_ids?: Array<ProjectId>;
3794
4535
  /**
@@ -3797,12 +4538,21 @@ type ConnectByoMachineRequest = {
3797
4538
  token_name?: ResourceName;
3798
4539
  };
3799
4540
  type ConnectByoMachineResponse = {
4541
+ /**
4542
+ * Newly created BYO machine.
4543
+ */
3800
4544
  machine: Machine;
3801
4545
  /**
3802
4546
  * Opaque bearer credential.
3803
4547
  */
3804
4548
  token: string;
4549
+ /**
4550
+ * Stored details of the issued daemon token; the token itself is never returned again.
4551
+ */
3805
4552
  token_record: MachineDaemonToken;
4553
+ /**
4554
+ * Grants created for the requested projects; empty when none were requested.
4555
+ */
3806
4556
  project_grants: Array<ProjectMachineGrant>;
3807
4557
  };
3808
4558
  type UpdateMachineRequest = {
@@ -3811,13 +4561,13 @@ type UpdateMachineRequest = {
3811
4561
  */
3812
4562
  cwd?: string;
3813
4563
  /**
3814
- * Environment variables set for processes started on the machine.
4564
+ * Environment variables for processes started on the machine. Replaces the whole map; omit to keep the current one.
3815
4565
  */
3816
4566
  env?: {
3817
4567
  [key: string]: string;
3818
4568
  };
3819
4569
  /**
3820
- * Environment variable names mapped to secret IDs (sec_...) whose values are set for processes started on the machine.
4570
+ * Environment variables set from secrets, keyed by variable name, for processes started on the machine.
3821
4571
  */
3822
4572
  secret_env?: {
3823
4573
  [key: string]: SecretId;
@@ -3827,17 +4577,53 @@ type UpdateMachineRequest = {
3827
4577
  * Shared machine fields composed into machine response schemas. Composing schemas close their final shape with unevaluatedProperties.
3828
4578
  */
3829
4579
  type MachineSummaryFields = {
4580
+ /**
4581
+ * Identifies the machine.
4582
+ */
3830
4583
  id: MachineId;
4584
+ /**
4585
+ * Organization that owns the machine.
4586
+ */
3831
4587
  org_id: OrganizationId;
4588
+ /**
4589
+ * Whether the machine is a bring-your-own computer or was created from a machine pool.
4590
+ */
3832
4591
  source_kind: MachineSourceKind;
4592
+ /**
4593
+ * Machine name; agent configs reference a BYO machine by this as machine_name.
4594
+ */
3833
4595
  display_name: ResourceName;
4596
+ /**
4597
+ * Free-form note about the machine; empty if none was set.
4598
+ */
3834
4599
  description: string;
4600
+ /**
4601
+ * Sandbox provider that hosts a pool machine; byo for bring-your-own machines.
4602
+ */
3835
4603
  provider: string;
4604
+ /**
4605
+ * Where the machine is in provisioning or deletion, independent of whether its daemon is connected.
4606
+ */
3836
4607
  lifecycle_state: MachineLifecycleState;
4608
+ /**
4609
+ * Whether the machine's daemon is connected now.
4610
+ */
3837
4611
  connection_state: MachineConnectionState;
4612
+ /**
4613
+ * When the daemon last registered or sent a heartbeat; null if it has never connected.
4614
+ */
3838
4615
  last_observed_at: Timestamp | null;
4616
+ /**
4617
+ * When the machine finished deleting; null while it still exists.
4618
+ */
3839
4619
  deleted_at: Timestamp | null;
4620
+ /**
4621
+ * When the machine record was created.
4622
+ */
3840
4623
  created_at: Timestamp;
4624
+ /**
4625
+ * When the machine record last changed.
4626
+ */
3841
4627
  updated_at: Timestamp;
3842
4628
  };
3843
4629
  type MachineSummary = MachineSummaryFields;
@@ -3859,21 +4645,51 @@ type ListVisibleMachinesResponse = {
3859
4645
  next_cursor: string | null;
3860
4646
  };
3861
4647
  type ProjectMachineGrant = {
4648
+ /**
4649
+ * Identifies the machine grant.
4650
+ */
3862
4651
  id: ProjectMachineGrantId;
4652
+ /**
4653
+ * Organization that owns the grant.
4654
+ */
3863
4655
  org_id: OrganizationId;
4656
+ /**
4657
+ * Project the grant gives access to.
4658
+ */
3864
4659
  project_id: ProjectId;
4660
+ /**
4661
+ * Machine the project's agents may use.
4662
+ */
3865
4663
  machine_id: MachineId;
4664
+ /**
4665
+ * Whether the grant was made directly or created for a machine from a pool grant.
4666
+ */
3866
4667
  source_kind: ProjectMachineGrantSourceKind;
4668
+ /**
4669
+ * Pool grant that created this grant; null for direct grants.
4670
+ */
3867
4671
  project_machine_pool_grant_id?: ProjectMachinePoolGrantId | null;
4672
+ /**
4673
+ * Free-form note about the grant; empty if none was set.
4674
+ */
3868
4675
  description: string;
4676
+ /**
4677
+ * Key-value metadata attached to the grant.
4678
+ */
3869
4679
  metadata: Metadata;
4680
+ /**
4681
+ * When the grant was created.
4682
+ */
3870
4683
  created_at: Timestamp;
4684
+ /**
4685
+ * When the grant last changed.
4686
+ */
3871
4687
  updated_at: Timestamp;
3872
4688
  };
3873
4689
  type CreateProjectMachineGrantRequest = {
3874
4690
  machine_id: MachineId;
3875
4691
  /**
3876
- * Optional note about this grant.
4692
+ * Free-form note stored with the grant.
3877
4693
  */
3878
4694
  description?: string;
3879
4695
  metadata?: Metadata;
@@ -3883,20 +4699,53 @@ type CreateProjectMachineGrantResponse = {
3883
4699
  machine: Machine;
3884
4700
  };
3885
4701
  type ListProjectMachineGrantsResponse = {
4702
+ /**
4703
+ * Project's machine grants on this page, each with its machine.
4704
+ */
3886
4705
  data: Array<ProjectMachineGrantListItem>;
4706
+ /**
4707
+ * Cursor for the next page, or null when this is the last page.
4708
+ */
3887
4709
  next_cursor: string | null;
3888
4710
  };
3889
4711
  type ProjectMachineGrantListItem = {
4712
+ /**
4713
+ * Grant that gives the project access to the machine.
4714
+ */
3890
4715
  grant: ProjectMachineGrant;
4716
+ /**
4717
+ * Summary of the granted machine.
4718
+ */
3891
4719
  machine: MachineSummary;
3892
4720
  };
3893
4721
  type ProjectMachinePoolGrant = {
4722
+ /**
4723
+ * Identifies the pool grant.
4724
+ */
3894
4725
  id: ProjectMachinePoolGrantId;
4726
+ /**
4727
+ * Organization that owns the grant.
4728
+ */
3895
4729
  org_id: OrganizationId;
4730
+ /**
4731
+ * Project the grant lets create machines from the pool.
4732
+ */
3896
4733
  project_id: ProjectId;
4734
+ /**
4735
+ * Pool the project may create machines from.
4736
+ */
3897
4737
  machine_pool_id: MachinePoolId;
4738
+ /**
4739
+ * Free-form note about the grant; empty if none was set.
4740
+ */
3898
4741
  description: string;
4742
+ /**
4743
+ * Default vCPUs for this project's machines from the pool; null uses the pool default.
4744
+ */
3899
4745
  default_machine_cpu: number | null;
4746
+ /**
4747
+ * Default memory in MB for this project's machines from the pool; null uses the pool default.
4748
+ */
3900
4749
  default_machine_memory_mb: number | null;
3901
4750
  /**
3902
4751
  * Env overlay merged over the pool's default_machine_env for machines materialized through this grant; a null entry removes the key.
@@ -3910,29 +4759,65 @@ type ProjectMachinePoolGrant = {
3910
4759
  default_machine_secret_env_overlay: {
3911
4760
  [key: string]: string | null;
3912
4761
  };
4762
+ /**
4763
+ * Provider options layered over the pool's for this project's machines.
4764
+ */
3913
4765
  default_machine_provider_options_overlay: {
3914
4766
  [key: string]: unknown;
3915
4767
  };
4768
+ /**
4769
+ * Working directory for this project's machines from the pool; empty uses the pool default.
4770
+ */
3916
4771
  default_cwd: string;
4772
+ /**
4773
+ * Most live machines this project can have from the pool; null means only the pool limit applies.
4774
+ */
3917
4775
  max_total_machines: number | null;
4776
+ /**
4777
+ * Most vCPUs across this project's live pool machines; null means only the pool limit applies.
4778
+ */
3918
4779
  max_total_cpu: number | null;
4780
+ /**
4781
+ * Most memory in MB across this project's live pool machines; null means only the pool limit applies.
4782
+ */
3919
4783
  max_total_memory_mb: number | null;
4784
+ /**
4785
+ * Fewest vCPUs one of this project's machines can request; null uses the pool minimum.
4786
+ */
3920
4787
  min_machine_cpu: number | null;
4788
+ /**
4789
+ * Least memory in MB one of this project's machines can request; null uses the pool minimum.
4790
+ */
3921
4791
  min_machine_memory_mb: number | null;
4792
+ /**
4793
+ * Most vCPUs one of this project's machines can request; null uses the pool maximum.
4794
+ */
3922
4795
  max_machine_cpu: number | null;
4796
+ /**
4797
+ * Most memory in MB one of this project's machines can request; null uses the pool maximum.
4798
+ */
3923
4799
  max_machine_memory_mb: number | null;
3924
4800
  /**
3925
4801
  * Idle minutes before deleting a machine created through this grant. Zero disables deletion for this grant; null inherits the pool default.
3926
4802
  */
3927
4803
  delete_after_idle_minutes: 0 | number | null;
4804
+ /**
4805
+ * Key-value metadata attached to the grant.
4806
+ */
3928
4807
  metadata: Metadata;
4808
+ /**
4809
+ * When the grant was created.
4810
+ */
3929
4811
  created_at: Timestamp;
4812
+ /**
4813
+ * When the grant last changed.
4814
+ */
3930
4815
  updated_at: Timestamp;
3931
4816
  };
3932
4817
  type CreateProjectMachinePoolGrantRequest = {
3933
4818
  machine_pool_id: MachinePoolId;
3934
4819
  /**
3935
- * Optional note about this grant.
4820
+ * Free-form note stored with the grant.
3936
4821
  */
3937
4822
  description?: string;
3938
4823
  /**
@@ -3994,7 +4879,7 @@ type CreateProjectMachinePoolGrantRequest = {
3994
4879
  */
3995
4880
  max_machine_memory_mb?: number;
3996
4881
  /**
3997
- * Idle minutes before deleting a machine created through this grant. Use 0 to disable for this grant; omit to inherit the pool default. Values from 1 through 4 are invalid.
4882
+ * Idle minutes before deleting a machine created through this grant. Use 0 to disable for this grant; omit to inherit the pool default.
3998
4883
  */
3999
4884
  delete_after_idle_minutes?: 0 | number;
4000
4885
  metadata?: Metadata;
@@ -4004,7 +4889,7 @@ type CreateProjectMachinePoolGrantRequest = {
4004
4889
  */
4005
4890
  type UpdateProjectMachinePoolGrantRequest = {
4006
4891
  /**
4007
- * Optional note about this grant.
4892
+ * Free-form note stored with the grant.
4008
4893
  */
4009
4894
  description?: string;
4010
4895
  /**
@@ -4066,7 +4951,7 @@ type UpdateProjectMachinePoolGrantRequest = {
4066
4951
  */
4067
4952
  max_machine_memory_mb?: number | null;
4068
4953
  /**
4069
- * Idle minutes before deleting a machine created through this grant. Use 0 to disable for this grant; null restores inheritance from the pool; omitted leaves it unchanged. Values from 1 through 4 are invalid.
4954
+ * Idle minutes before deleting a machine created through this grant. Use 0 to disable for this grant; null restores inheritance from the pool; omitted leaves it unchanged.
4070
4955
  */
4071
4956
  delete_after_idle_minutes?: 0 | number | null;
4072
4957
  metadata?: Metadata;
@@ -4097,14 +4982,41 @@ type CreateMachineDaemonTokenRequest = {
4097
4982
  metadata?: Metadata;
4098
4983
  };
4099
4984
  type MachineDaemonToken = {
4985
+ /**
4986
+ * Identifies the daemon token.
4987
+ */
4100
4988
  id: MachineDaemonTokenId;
4989
+ /**
4990
+ * Organization that owns the token.
4991
+ */
4101
4992
  org_id: OrganizationId;
4993
+ /**
4994
+ * Machine whose daemon authenticates with this token.
4995
+ */
4102
4996
  machine_id: MachineId;
4997
+ /**
4998
+ * Label for the token; defaults to daemon.
4999
+ */
4103
5000
  name: ResourceName;
5001
+ /**
5002
+ * Key-value metadata attached to the token.
5003
+ */
4104
5004
  metadata: Metadata;
5005
+ /**
5006
+ * When the token was issued.
5007
+ */
4105
5008
  created_at: Timestamp;
5009
+ /**
5010
+ * Approximate time the daemon last authenticated with this token; null if never used.
5011
+ */
4106
5012
  last_used_at: Timestamp | null;
5013
+ /**
5014
+ * When the token was revoked; null while it is still valid.
5015
+ */
4107
5016
  revoked_at: Timestamp | null;
5017
+ /**
5018
+ * Why the token was revoked, such as machine_deleted; empty while valid.
5019
+ */
4108
5020
  revoke_reason: string;
4109
5021
  };
4110
5022
  type CreateMachineDaemonTokenResponse = {
@@ -4198,10 +5110,25 @@ type UpdateProjectRequest = {
4198
5110
  * Shared project fields composed into project response schemas. Composing schemas close their final shape with unevaluatedProperties.
4199
5111
  */
4200
5112
  type ProjectFields = {
5113
+ /**
5114
+ * Identifies the project.
5115
+ */
4201
5116
  id: ProjectId;
5117
+ /**
5118
+ * Organization that owns the project.
5119
+ */
4202
5120
  org_id: OrganizationId;
5121
+ /**
5122
+ * Display name of the project.
5123
+ */
4203
5124
  name: ResourceName;
5125
+ /**
5126
+ * When the project was created.
5127
+ */
4204
5128
  created_at: Timestamp;
5129
+ /**
5130
+ * When the project last changed.
5131
+ */
4205
5132
  updated_at: Timestamp;
4206
5133
  };
4207
5134
  type Project = ProjectFields;
@@ -4592,7 +5519,13 @@ type IntegrationConversation = {
4592
5519
  [key: string]: unknown;
4593
5520
  };
4594
5521
  type IntegrationSubscriptionAttachment = {
5522
+ /**
5523
+ * Integration that forwards the conversation's activity.
5524
+ */
4595
5525
  integration_id: IntegrationId;
5526
+ /**
5527
+ * Provider conversation to subscribe the agent to, such as a Slack channel.
5528
+ */
4596
5529
  conversation: IntegrationConversation;
4597
5530
  };
4598
5531
  type CreateIntegrationSubscriptionRequest = {
@@ -4702,13 +5635,13 @@ type ResourceNameFilter = string;
4702
5635
  */
4703
5636
  type MachineSourceKindFilter = MachineSourceKind;
4704
5637
  /**
4705
- * Metadata key/value filters, encoded as metadata[key]=value.
5638
+ * Return only secrets whose metadata includes these key-value pairs.
4706
5639
  */
4707
5640
  type SecretMetadataFilter = {
4708
5641
  [key: string]: string;
4709
5642
  };
4710
5643
  /**
4711
- * Filter secrets by material kind.
5644
+ * Return only secrets that hold this type of credential.
4712
5645
  */
4713
5646
  type SecretKindFilter = SecretKind;
4714
5647
  /**
@@ -4716,7 +5649,7 @@ type SecretKindFilter = SecretKind;
4716
5649
  */
4717
5650
  type SkillOwnerKindFilter = 'org' | 'project' | 'user';
4718
5651
  /**
4719
- * Required with owner_kind=project and invalid with other owner kinds.
5652
+ * Owning project to filter by. Required when owner_kind is project.
4720
5653
  */
4721
5654
  type SkillOwnerProjectIdFilter = ProjectId;
4722
5655
  /**
@@ -4728,7 +5661,7 @@ type SkillAvailabilitySourceFilter = 'direct' | 'grant';
4728
5661
  */
4729
5662
  type SecretOwnerKindFilter = 'org' | 'project' | 'user';
4730
5663
  /**
4731
- * Required with owner_kind=project and invalid with other owner kinds.
5664
+ * Owning project to filter by. Required when owner_kind is project.
4732
5665
  */
4733
5666
  type SecretOwnerProjectIdFilter = ProjectId;
4734
5667
  /**
@@ -7891,7 +8824,7 @@ type ListSkillsData = {
7891
8824
  */
7892
8825
  owner_kind?: 'org' | 'project' | 'user';
7893
8826
  /**
7894
- * Required with owner_kind=project and invalid with other owner kinds.
8827
+ * Owning project to filter by. Required when owner_kind is project.
7895
8828
  */
7896
8829
  owner_project_id?: ProjectId;
7897
8830
  sort?: ResourceListSort;
@@ -9471,7 +10404,7 @@ type ListSecretsData = {
9471
10404
  */
9472
10405
  name?: string;
9473
10406
  /**
9474
- * Filter secrets by material kind.
10407
+ * Return only secrets that hold this type of credential.
9475
10408
  */
9476
10409
  kind?: SecretKind;
9477
10410
  /**
@@ -9479,7 +10412,7 @@ type ListSecretsData = {
9479
10412
  */
9480
10413
  owner_kind?: 'org' | 'project' | 'user';
9481
10414
  /**
9482
- * Required with owner_kind=project and invalid with other owner kinds.
10415
+ * Owning project to filter by. Required when owner_kind is project.
9483
10416
  */
9484
10417
  owner_project_id?: ProjectId;
9485
10418
  /**
@@ -9487,7 +10420,7 @@ type ListSecretsData = {
9487
10420
  */
9488
10421
  mcp_oauth_flow_id?: McpoAuthFlowId;
9489
10422
  /**
9490
- * Metadata key/value filters, encoded as metadata[key]=value.
10423
+ * Return only secrets whose metadata includes these key-value pairs.
9491
10424
  */
9492
10425
  metadata?: {
9493
10426
  [key: string]: string;
@@ -13360,6 +14293,9 @@ type ListAgentInteractionsData = {
13360
14293
  agentID: string;
13361
14294
  };
13362
14295
  query?: {
14296
+ /**
14297
+ * Return only interactions in this state. Omit to return all.
14298
+ */
13363
14299
  state?: AgentInteractionState;
13364
14300
  /**
13365
14301
  * Also return interactions from every subagent beneath this agent. Resolve those against the subagent's own agent_id.
@@ -14468,7 +15404,7 @@ type ListProjectAvailableSecretsData = {
14468
15404
  */
14469
15405
  name?: string;
14470
15406
  /**
14471
- * Filter secrets by material kind.
15407
+ * Return only secrets that hold this type of credential.
14472
15408
  */
14473
15409
  kind?: SecretKind;
14474
15410
  /**
@@ -14480,7 +15416,7 @@ type ListProjectAvailableSecretsData = {
14480
15416
  */
14481
15417
  availability_source?: 'direct' | 'grant';
14482
15418
  /**
14483
- * Metadata key/value filters, encoded as metadata[key]=value.
15419
+ * Return only secrets whose metadata includes these key-value pairs.
14484
15420
  */
14485
15421
  metadata?: {
14486
15422
  [key: string]: string;