diff --git a/package.json b/package.json index 8584c1c..40fb6d6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@anduril-industries/lattice-sdk", - "version": "3.0.0", + "version": "3.1.0", "private": false, "repository": "github:anduril/lattice-sdk-javascript", "license": "See LICENSE", diff --git a/reference.md b/reference.md index f0bb9f0..8dbbc9b 100644 --- a/reference.md +++ b/reference.md @@ -359,7 +359,25 @@ await client.entities.longPollEntityEvents({
-Establishes a persistent connection to stream entity events as they occur. +Establishes a server-sent events (SSE) connection that streams entity data in real-time. +This is a one-way connection from server to client that follows the SSE protocol with text/event-stream content type. + +This endpoint enables clients to maintain a real-time view of the common operational picture (COP) +by first streaming all pre-existing entities that match filter criteria, then continuously delivering +updates as entities are created, modified, or deleted. + +The server first sends events with type PREEXISTING for all live entities matching the filter that existed before the stream was open, +then streams CREATE events for newly created entities, UPDATE events when existing entities change, and DELETED events when entities are removed. The stream remains open +indefinitely unless preExistingOnly is set to true. + +Heartbeat messages can be configured to maintain connection health and detect disconnects by setting the heartbeatIntervalMS +parameter. These heartbeats help keep the connection alive and allow clients to verify the server is still responsive. + +Clients can optimize bandwidth usage by specifying which entity components they need populated using the componentsToInclude parameter. +This allows receiving only relevant data instead of complete entities. + +The connection automatically recovers from temporary disconnections, resuming the stream where it left off. Unlike polling approaches, +this provides real-time updates with minimal latency and reduced server load.
@@ -426,8 +444,14 @@ for await (const item of response) {
-Submit a request to create a task and schedule it for delivery. Tasks, once delivered, will -be asynchronously updated by their destined agent. +Creates a new Task in the system with the specified parameters. + +This method initiates a new task with a unique ID (either provided or auto-generated), +sets the initial task state to STATUS_CREATED, and establishes task ownership. The task +can be assigned to a specific agent through the Relations field. + +Once created, a task enters the lifecycle workflow and can be tracked, updated, and managed +through other Tasks API endpoints.
@@ -482,6 +506,27 @@ await client.tasks.createTask();
+#### 📝 Description + +
+
+ +
+
+ +Retrieves a specific Task by its ID, with options to select a particular task version or view. + +This method returns detailed information about a task including its current status, +specification, relations, and other metadata. The response includes the complete Task object +with all associated fields. + +By default, the method returns the latest definition version of the task from the manager's +perspective. +
+
+
+
+ #### 🔌 Usage
@@ -539,7 +584,17 @@ await client.tasks.getTask("taskId");
-Update the status of a task. +Updates the status of a Task as it progresses through its lifecycle. + +This method allows agents or operators to report the current state of a task, +which could include changes to task status, and error information. + +Each status update increments the task's status_version. When updating status, +clients must provide the current version to ensure consistency. The system rejects +updates with mismatched versions to prevent race conditions. + +Terminal states (`STATUS_DONE_OK` and `STATUS_DONE_NOT_OK`) are permanent; once a task +reaches these states, no further updates are allowed.
@@ -610,7 +665,21 @@ await client.tasks.updateTaskStatus("taskId");
-Query for tasks by a specified search criteria. +Searches for Tasks that match specified filtering criteria and returns matching tasks in paginated form. + +This method allows filtering tasks based on multiple criteria including: +- Parent task relationships +- Task status (with inclusive or exclusive filtering) +- Update time ranges +- Task view (manager or agent perspective) +- Task assignee +- Task type (via exact URL matches or prefix matching) + +Results are returned in pages. When more results are available than can be returned in a single +response, a page_token is provided that can be used in subsequent requests to retrieve the next +set of results. + +By default, this returns the latest task version for each matching task from the manager's perspective.
@@ -673,8 +742,25 @@ await client.tasks.queryTasks();
-This is a long polling API that will block until a new task is ready for delivery. If no new task is -available then the server will hold on to your request for up to 5 minutes, after that 5 minute timeout +Establishes a server streaming connection that delivers tasks to taskable agents for execution. + +This method creates a persistent connection from Tasks API to an agent, allowing the server +to push tasks to the agent as they become available. The agent receives a stream of tasks that +match its selector criteria (entity IDs). + +The stream delivers three types of requests: +- ExecuteRequest: Contains a new task for the agent to execute +- CancelRequest: Indicates a task should be canceled +- CompleteRequest: Indicates a task should be completed + +This is the primary method for taskable agents to receive and process tasks in real-time. +Agents should maintain this connection and process incoming tasks according to their capabilities. + +When an agent receives a task, it should update the task status using the UpdateStatus endpoint +to provide progress information back to Tasks API. + +This is a long polling API that will block until a new task is ready for delivery. If no new task is +available then the server will hold on to your request for up to 5 minutes, after that 5 minute timeout period you will be expected to reinitiate a new request.
diff --git a/src/Client.ts b/src/Client.ts index 483efe7..16340f7 100644 --- a/src/Client.ts +++ b/src/Client.ts @@ -26,8 +26,8 @@ export class LatticeClient { { "X-Fern-Language": "JavaScript", "X-Fern-SDK-Name": "@anduril-industries/lattice-sdk", - "X-Fern-SDK-Version": "3.0.0", - "User-Agent": "@anduril-industries/lattice-sdk/3.0.0", + "X-Fern-SDK-Version": "3.1.0", + "User-Agent": "@anduril-industries/lattice-sdk/3.1.0", "X-Fern-Runtime": core.RUNTIME.type, "X-Fern-Runtime-Version": core.RUNTIME.version, }, diff --git a/src/api/resources/entities/client/Client.ts b/src/api/resources/entities/client/Client.ts index 28973e5..5b9e1ac 100644 --- a/src/api/resources/entities/client/Client.ts +++ b/src/api/resources/entities/client/Client.ts @@ -476,7 +476,25 @@ export class Entities { } /** - * Establishes a persistent connection to stream entity events as they occur. + * Establishes a server-sent events (SSE) connection that streams entity data in real-time. + * This is a one-way connection from server to client that follows the SSE protocol with text/event-stream content type. + * + * This endpoint enables clients to maintain a real-time view of the common operational picture (COP) + * by first streaming all pre-existing entities that match filter criteria, then continuously delivering + * updates as entities are created, modified, or deleted. + * + * The server first sends events with type PREEXISTING for all live entities matching the filter that existed before the stream was open, + * then streams CREATE events for newly created entities, UPDATE events when existing entities change, and DELETED events when entities are removed. The stream remains open + * indefinitely unless preExistingOnly is set to true. + * + * Heartbeat messages can be configured to maintain connection health and detect disconnects by setting the heartbeatIntervalMS + * parameter. These heartbeats help keep the connection alive and allow clients to verify the server is still responsive. + * + * Clients can optimize bandwidth usage by specifying which entity components they need populated using the componentsToInclude parameter. + * This allows receiving only relevant data instead of complete entities. + * + * The connection automatically recovers from temporary disconnections, resuming the stream where it left off. Unlike polling approaches, + * this provides real-time updates with minimal latency and reduced server load. */ public streamEntities( request: Lattice.EntityStreamRequest = {}, diff --git a/src/api/resources/tasks/client/Client.ts b/src/api/resources/tasks/client/Client.ts index 07ea354..88f4374 100644 --- a/src/api/resources/tasks/client/Client.ts +++ b/src/api/resources/tasks/client/Client.ts @@ -24,8 +24,14 @@ export class Tasks { } /** - * Submit a request to create a task and schedule it for delivery. Tasks, once delivered, will - * be asynchronously updated by their destined agent. + * Creates a new Task in the system with the specified parameters. + * + * This method initiates a new task with a unique ID (either provided or auto-generated), + * sets the initial task state to STATUS_CREATED, and establishes task ownership. The task + * can be assigned to a specific agent through the Relations field. + * + * Once created, a task enters the lifecycle workflow and can be tracked, updated, and managed + * through other Tasks API endpoints. * * @param {Lattice.TaskCreation} request * @param {Tasks.RequestOptions} requestOptions - Request-specific configuration. @@ -106,6 +112,15 @@ export class Tasks { } /** + * Retrieves a specific Task by its ID, with options to select a particular task version or view. + * + * This method returns detailed information about a task including its current status, + * specification, relations, and other metadata. The response includes the complete Task object + * with all associated fields. + * + * By default, the method returns the latest definition version of the task from the manager's + * perspective. + * * @param {string} taskId - ID of task to return * @param {Tasks.RequestOptions} requestOptions - Request-specific configuration. * @@ -182,7 +197,17 @@ export class Tasks { } /** - * Update the status of a task. + * Updates the status of a Task as it progresses through its lifecycle. + * + * This method allows agents or operators to report the current state of a task, + * which could include changes to task status, and error information. + * + * Each status update increments the task's status_version. When updating status, + * clients must provide the current version to ensure consistency. The system rejects + * updates with mismatched versions to prevent race conditions. + * + * Terminal states (`STATUS_DONE_OK` and `STATUS_DONE_NOT_OK`) are permanent; once a task + * reaches these states, no further updates are allowed. * * @param {string} taskId - ID of task to update status of * @param {Lattice.TaskStatusUpdate} request @@ -271,7 +296,21 @@ export class Tasks { } /** - * Query for tasks by a specified search criteria. + * Searches for Tasks that match specified filtering criteria and returns matching tasks in paginated form. + * + * This method allows filtering tasks based on multiple criteria including: + * - Parent task relationships + * - Task status (with inclusive or exclusive filtering) + * - Update time ranges + * - Task view (manager or agent perspective) + * - Task assignee + * - Task type (via exact URL matches or prefix matching) + * + * Results are returned in pages. When more results are available than can be returned in a single + * response, a page_token is provided that can be used in subsequent requests to retrieve the next + * set of results. + * + * By default, this returns the latest task version for each matching task from the manager's perspective. * * @param {Lattice.TaskQuery} request * @param {Tasks.RequestOptions} requestOptions - Request-specific configuration. @@ -355,6 +394,23 @@ export class Tasks { } /** + * Establishes a server streaming connection that delivers tasks to taskable agents for execution. + * + * This method creates a persistent connection from Tasks API to an agent, allowing the server + * to push tasks to the agent as they become available. The agent receives a stream of tasks that + * match its selector criteria (entity IDs). + * + * The stream delivers three types of requests: + * - ExecuteRequest: Contains a new task for the agent to execute + * - CancelRequest: Indicates a task should be canceled + * - CompleteRequest: Indicates a task should be completed + * + * This is the primary method for taskable agents to receive and process tasks in real-time. + * Agents should maintain this connection and process incoming tasks according to their capabilities. + * + * When an agent receives a task, it should update the task status using the UpdateStatus endpoint + * to provide progress information back to Tasks API. + * * This is a long polling API that will block until a new task is ready for delivery. If no new task is * available then the server will hold on to your request for up to 5 minutes, after that 5 minute timeout * period you will be expected to reinitiate a new request. diff --git a/src/api/resources/tasks/client/requests/TaskCreation.ts b/src/api/resources/tasks/client/requests/TaskCreation.ts index ef80460..89d8356 100644 --- a/src/api/resources/tasks/client/requests/TaskCreation.ts +++ b/src/api/resources/tasks/client/requests/TaskCreation.ts @@ -16,7 +16,7 @@ export interface TaskCreation { displayName?: string; /** Longer, free form human readable description of this Task. */ description?: string; - /** Full set of task parameters. */ + /** The path for the Protobuf task definition, and the complete task data. */ specification?: Lattice.GoogleProtobufAny; author?: Lattice.Principal; /** diff --git a/src/api/resources/tasks/client/requests/TaskQuery.ts b/src/api/resources/tasks/client/requests/TaskQuery.ts index 2643d24..198975b 100644 --- a/src/api/resources/tasks/client/requests/TaskQuery.ts +++ b/src/api/resources/tasks/client/requests/TaskQuery.ts @@ -9,7 +9,7 @@ export interface TaskQuery { pageToken?: string; /** * If present matches Tasks with this parent Task ID. - * Note: this is mutually exclusive with all other query parameters, i.e., either provide parent Task ID, or + * Note: this is mutually exclusive with all other query parameters, for example, either provide parent task ID, or * any of the remaining parameters, but not both. */ parentTaskId?: string; diff --git a/src/api/types/Agent.ts b/src/api/types/Agent.ts index bcb3214..ef20026 100644 --- a/src/api/types/Agent.ts +++ b/src/api/types/Agent.ts @@ -1,7 +1,7 @@ // This file was auto-generated by Fern from our API Definition. /** - * Represents an Agent in the COP. + * Represents an agent capable of processing tasks. */ export interface Agent { /** Entity ID of the agent. */ diff --git a/src/api/types/AgentRequest.ts b/src/api/types/AgentRequest.ts index b7852aa..7cf61a5 100644 --- a/src/api/types/AgentRequest.ts +++ b/src/api/types/AgentRequest.ts @@ -2,6 +2,18 @@ import type * as Lattice from "../index.js"; +/** + * Response streamed to an agent containing task actions to perform. + * + * This message is streamed from Tasks API to agents and contains one of three + * possible requests: execute a task, cancel a task, or complete a task. The agent + * should process these requests according to its capabilities and report status + * updates back to Tasks API using the UpdateStatus endpoint. + * + * Multiple responses may be sent for different tasks, and the agent should maintain + * the connection to receive ongoing task requests. The connection may also be used + * for heartbeat messages to ensure the agent is still responsive. + */ export interface AgentRequest { executeRequest?: Lattice.ExecuteRequest; cancelRequest?: Lattice.CancelRequest; diff --git a/src/api/types/Allocation.ts b/src/api/types/Allocation.ts index d4e468b..d405248 100644 --- a/src/api/types/Allocation.ts +++ b/src/api/types/Allocation.ts @@ -3,9 +3,9 @@ import type * as Lattice from "../index.js"; /** - * Allocation contains a list of agents allocated to a Task. + * Allocation contains a list of agents allocated to a task. */ export interface Allocation { - /** Agents actively being utilized in a Task. */ + /** Agents actively being utilized in a task. */ activeAgents?: Lattice.Agent[]; } diff --git a/src/api/types/CancelRequest.ts b/src/api/types/CancelRequest.ts index f6e1fee..de9b111 100644 --- a/src/api/types/CancelRequest.ts +++ b/src/api/types/CancelRequest.ts @@ -3,10 +3,11 @@ import type * as Lattice from "../index.js"; /** - * Request to Cancel a Task. + * The request to cancel a task. + * Contains the task, and the assignee of the request to cancel the task. */ export interface CancelRequest { - /** ID of the Task to cancel. */ + /** The unique task ID of the task to cancel. */ taskId?: string; /** * The assignee of the Task. Useful for agent routing where an endpoint owns multiple agents, diff --git a/src/api/types/CompleteRequest.ts b/src/api/types/CompleteRequest.ts index c88bb9f..7c0ce4a 100644 --- a/src/api/types/CompleteRequest.ts +++ b/src/api/types/CompleteRequest.ts @@ -1,7 +1,8 @@ // This file was auto-generated by Fern from our API Definition. /** - * Request to Complete a Task. + * The request to complete a task. + * Contains the unique ID of the task to complete. */ export interface CompleteRequest { /** ID of the task to complete. */ diff --git a/src/api/types/Entity.ts b/src/api/types/Entity.ts index 4ae9625..3ca6e4f 100644 --- a/src/api/types/Entity.ts +++ b/src/api/types/Entity.ts @@ -8,8 +8,8 @@ import type * as Lattice from "../index.js"; */ export interface Entity { /** - * A Globally Unique Identifier (GUID) for your entity. If this field is empty, the Entity Manager API - * automatically generates an ID when it creates the entity. + * A Globally Unique Identifier (GUID) for your entity. This is a required + * field. */ entityId?: string; /** diff --git a/src/api/types/ExecuteRequest.ts b/src/api/types/ExecuteRequest.ts index 35ff913..882655e 100644 --- a/src/api/types/ExecuteRequest.ts +++ b/src/api/types/ExecuteRequest.ts @@ -3,9 +3,10 @@ import type * as Lattice from "../index.js"; /** - * Request to execute a Task. + * The request to execute a task. + * Contains the unique ID of the task to execute. */ export interface ExecuteRequest { - /** Task to execute. */ + /** The task to execute. */ task?: Lattice.Task; } diff --git a/src/api/types/Owner.ts b/src/api/types/Owner.ts index d10bd80..fe7753c 100644 --- a/src/api/types/Owner.ts +++ b/src/api/types/Owner.ts @@ -1,7 +1,7 @@ // This file was auto-generated by Fern from our API Definition. /** - * Owner designates the entity responsible for writes of Task data. + * Owner designates the entity responsible for writes of task data. */ export interface Owner { /** Entity ID of the owner. */ diff --git a/src/api/types/Principal.ts b/src/api/types/Principal.ts index f668c62..8954be9 100644 --- a/src/api/types/Principal.ts +++ b/src/api/types/Principal.ts @@ -3,7 +3,7 @@ import type * as Lattice from "../index.js"; /** - * A Principal is an entity that has authority over this Task. + * A Principal is an entity that has authority over this task. */ export interface Principal { system?: Lattice.System; diff --git a/src/api/types/Relations.ts b/src/api/types/Relations.ts index 7720235..4f2c551 100644 --- a/src/api/types/Relations.ts +++ b/src/api/types/Relations.ts @@ -3,11 +3,12 @@ import type * as Lattice from "../index.js"; /** - * Relations describes the relationships of this Task, such as assignment, or if the Task has any parents. + * Describes the relationships associated with this task: the system assigned to + * execute the task, and the parent task, if one exists. */ export interface Relations { - /** Who or what, if anyone, this Task is currently assigned to. */ + /** The system, user, or team assigned to the task. */ assignee?: Lattice.Principal; - /** If this Task is a "sub-Task", what is its parent, none if empty. */ + /** Identifies the parent task if the task is a sub-task. */ parentTaskId?: string; } diff --git a/src/api/types/Replication.ts b/src/api/types/Replication.ts index ef76a48..30a4e72 100644 --- a/src/api/types/Replication.ts +++ b/src/api/types/Replication.ts @@ -1,9 +1,9 @@ // This file was auto-generated by Fern from our API Definition. /** - * Any metadata associated with the replication of a Task. + * Any metadata associated with the replication of a task. */ export interface Replication { - /** Time by which this Task should be assumed to be stale. */ + /** The time by which this task should be assumed to be stale. */ staleTime?: string; } diff --git a/src/api/types/System.ts b/src/api/types/System.ts index c696c9b..08bf411 100644 --- a/src/api/types/System.ts +++ b/src/api/types/System.ts @@ -11,7 +11,7 @@ export interface System { /** * Whether the System Principal (for example, an Asset) can own scheduling. * This means we bypass manager-owned scheduling and defer to the system - * Principal to handle scheduling and give us status updates for the Task. + * Principal to handle scheduling and give us status updates for the task. * Regardless of the value defined by the client, the Task Manager will * determine and set this value appropriately. */ diff --git a/src/api/types/Task.ts b/src/api/types/Task.ts index c7ec9f9..903e596 100644 --- a/src/api/types/Task.ts +++ b/src/api/types/Task.ts @@ -3,37 +3,45 @@ import type * as Lattice from "../index.js"; /** - * A Task is something an agent can be asked to do. + * A task represents a structured unit of work that can be assigned to an agent for execution. + * + * Tasks are the fundamental building blocks of work assignment in the Lattice. + * Each task has a unique identifier, a specification defining what needs to be done, + * status information tracking its progress, and various metadata facilitating its lifecycle management. + * + * Tasks can be related to each other, through parent-child relationships, assigned to + * specific agents, and tracked through a well-defined state machine from creation to completion. + * They support rich status reporting, including progress updates, error handling, and results. */ export interface Task { - /** Version of this Task. */ + /** Version of this task. */ version?: Lattice.TaskVersion; - /** DEPRECATED: Human readable display name for this Task, should be short (<100 chars). */ + /** DEPRECATED: Human readable display name for this task, should be short (<100 chars). */ displayName?: string; - /** Full Task parameterization. */ + /** The path for the Protobuf task definition, and the complete task data. */ specification?: Lattice.GoogleProtobufAny; - /** Records who created this Task. This field will not change after the Task has been created. */ + /** Records who created this task. This field will not change after the task has been created. */ createdBy?: Lattice.Principal; - /** Records who updated this Task last. */ + /** Records who updated this task last. */ lastUpdatedBy?: Lattice.Principal; /** Records the time of last update. */ lastUpdateTime?: string; - /** The status of this Task. */ + /** The status of this task. */ status?: Lattice.TaskStatus; - /** If the Task has been scheduled to execute, what time it should execute at. */ + /** If the task has been scheduled to execute, what time it should execute at. */ scheduledTime?: string; - /** Any related Tasks associated with this, typically includes an assignee for this Task and/or a parent. */ + /** Any related Tasks associated with this, typically includes an assignee for this task and/or a parent. */ relations?: Lattice.Relations; - /** Longer, free form human readable description of this Task */ + /** Longer, free form human readable description of this task */ description?: string; /** - * If set, execution of this Task is managed elsewhere, not by Task Manager. - * In other words, Task manager will not attempt to update the assigned agent with execution instructions. + * If set, execution of this task is managed elsewhere, not by Task Manager. + * In other words, task manager will not attempt to update the assigned agent with execution instructions. */ isExecutedElsewhere?: boolean; - /** Time of Task creation. */ + /** Time of task creation. */ createTime?: string; - /** If populated, designates this to be a replicated Task. */ + /** If populated, designates this to be a replicated task. */ replication?: Lattice.Replication; /** * If populated, indicates an initial set of entities that can be used to execute an entity aware task @@ -43,7 +51,7 @@ export interface Task { */ initialEntities?: Lattice.TaskEntity[]; /** - * The networked owner of this Task. It is used to ensure that linear writes occur on the node responsible + * The networked owner of this task. It is used to ensure that linear writes occur on the node responsible * for replication of task data to other nodes running Task Manager. */ owner?: Lattice.Owner; diff --git a/src/api/types/TaskEntity.ts b/src/api/types/TaskEntity.ts index 4520e1f..5c4f773 100644 --- a/src/api/types/TaskEntity.ts +++ b/src/api/types/TaskEntity.ts @@ -3,10 +3,14 @@ import type * as Lattice from "../index.js"; /** - * Wrapper of an entity passed in Tasking, used to hold an additional information, and as a future extension point. + * An entity wrapper used in task definitions, with additional metadata. + * + * TaskEntity wraps an entity reference with additional contextual information for task execution. + * This structure allows entities to be passed to tasks with supplementary metadata that aids + * in proper task execution, while also serving as an extension point for future capabilities. */ export interface TaskEntity { - /** The wrapped entity-manager entity. */ + /** The wrapped entity. */ entity?: Lattice.Entity; /** Indicates that this entity was generated from a snapshot of a live entity. */ snapshot?: boolean; diff --git a/src/api/types/TaskError.ts b/src/api/types/TaskError.ts index 2543d5f..9e72047 100644 --- a/src/api/types/TaskError.ts +++ b/src/api/types/TaskError.ts @@ -3,10 +3,14 @@ import type * as Lattice from "../index.js"; /** - * TaskError contains an error code and message typically associated to a Task. + * Error information associated with a task. + * + * TaskError contains structured error details, including an error code, a human-readable + * message, and optional extended error information. This structure is used when a task + * encounters problems during its lifecycle. */ export interface TaskError { - /** Error code for Task error. */ + /** Error code for task error. */ code?: TaskError.Code; /** Descriptive human-readable string regarding this error. */ message?: string; @@ -15,7 +19,7 @@ export interface TaskError { } export namespace TaskError { - /** Error code for Task error. */ + /** Error code for task error. */ export const Code = { ErrorCodeInvalid: "ERROR_CODE_INVALID", ErrorCodeCancelled: "ERROR_CODE_CANCELLED", diff --git a/src/api/types/TaskQueryResults.ts b/src/api/types/TaskQueryResults.ts index 4880998..ce68a83 100644 --- a/src/api/types/TaskQueryResults.ts +++ b/src/api/types/TaskQueryResults.ts @@ -2,6 +2,15 @@ import type * as Lattice from "../index.js"; +/** + * Response containing tasks that match the query criteria. + * + * This message returns a list of Task objects that satisfy the filter conditions + * specified in the request. When there are more matching tasks than can be returned + * in a single response, a page_token is provided to retrieve the next batch in + * a subsequent request. An empty tasks list with no page_token indicates that + * there are no more matching tasks. + */ export interface TaskQueryResults { tasks?: Lattice.Task[]; /** diff --git a/src/api/types/TaskStatus.ts b/src/api/types/TaskStatus.ts index 7eb3560..9f59251 100644 --- a/src/api/types/TaskStatus.ts +++ b/src/api/types/TaskStatus.ts @@ -3,28 +3,32 @@ import type * as Lattice from "../index.js"; /** - * TaskStatus is contains information regarding the status of a Task at any given time. Can include related information - * such as any progress towards Task completion, or any associated results if Task completed. + * Comprehensive status information for a task at a given point in time. + * + * TaskStatus contains all status-related information for a task, including its current state, + * any error conditions, progress details, results, timing information, and resource allocations. + * This object evolves throughout a task's lifecycle, providing increasing detail as the task + * progresses from creation through execution to completion. */ export interface TaskStatus { - /** Status of the Task. */ + /** Status of the task. */ status?: TaskStatus.Status; - /** Any errors associated with the Task. */ + /** Any errors associated with the task. */ taskError?: Lattice.TaskError; - /** Any incremental progress on the Task, should be from the tasks/v* /progress folder. */ + /** Any incremental progress on the task, should be from the tasks/v* /progress folder. */ progress?: Lattice.GoogleProtobufAny; - /** Any final result of the Task, should be from tasks/v* /result folder. */ + /** Any final result of the task, should be from tasks/v* /result folder. */ result?: Lattice.GoogleProtobufAny; - /** Time the Task began execution, may not be known even for executing Tasks. */ + /** Time the task began execution, may not be known even for executing Tasks. */ startTime?: string; - /** Any estimate for how the Task will progress, should be from tasks/v* /estimates folder. */ + /** Any estimate for how the task will progress, should be from tasks/v* /estimates folder. */ estimate?: Lattice.GoogleProtobufAny; - /** Any allocated agents of the Task. */ + /** Any allocated agents of the task. */ allocation?: Lattice.Allocation; } export namespace TaskStatus { - /** Status of the Task. */ + /** Status of the task. */ export const Status = { StatusInvalid: "STATUS_INVALID", StatusCreated: "STATUS_CREATED", diff --git a/src/api/types/TaskVersion.ts b/src/api/types/TaskVersion.ts index 71d163e..510cf6f 100644 --- a/src/api/types/TaskVersion.ts +++ b/src/api/types/TaskVersion.ts @@ -1,13 +1,23 @@ // This file was auto-generated by Fern from our API Definition. /** - * Version of a Task. + * Versioning information for a task. + * + * TaskVersion provides a unique identifier for each task, along with separate version counters + * for tracking changes to the task's definition and its status. This versioning system enables + * optimistic concurrency control, ensuring that updates from multiple sources don't conflict. */ export interface TaskVersion { - /** The unique ID for this Task. */ + /** The unique identifier for this task, used to distinguish it from all other tasks in the system. */ taskId?: string; - /** Increments on definition (i.e. not TaskStatus) change. 0 is unset, starts at 1 on creation. */ + /** + * Counter that increments on changes to the task definition. + * Unset (0) initially, starts at 1 on creation, and increments with each update to task fields. + */ definitionVersion?: number; - /** Increments on changes to TaskStatus. 0 is unset, starts at 1 on creation. */ + /** + * Counter that increments on changes to TaskStatus. + * Unset (0) initially, starts at 1 on creation, and increments with each status update. + */ statusVersion?: number; } diff --git a/src/version.ts b/src/version.ts index b54c0db..8bccdd4 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const SDK_VERSION = "2.5.0"; +export const SDK_VERSION = "3.1.0";