Package com.tnsai.exceptions

Class TaskCompleteException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.tnsai.exceptions.TnsAIException

com.tnsai.exceptions.TaskCompleteException

All Implemented Interfaces:

Serializable

public class TaskCompleteException
extends TnsAIException

Signals that a task has been completed and the agent loop should terminate.

This is a control flow exception, not an error. It's thrown by completion signal actions to indicate successful task termination.

Usage

 @ActionSpec(type = ActionType.LOCAL)
 @CompletionSignal
 public void markComplete(String summary) {
     // Do any final cleanup
     saveResults();

     // Signal completion
     throw new TaskCompleteException(summary);
 }

 // With result data
 throw TaskCompleteException.withResult("Task done", Map.of(
     "filesCreated", 5,
     "testsRun", 42
 ));
 

Handling in Agent Loop

 try {
     agent.run(task);
 } catch (TaskCompleteException e) {
     System.out.println("Task completed: " + e.getSummary());
     System.out.println("Result: " + e.getResult());
     System.out.println("Success: " + e.isSuccess());
 }
 

Comparison with CompletionCriteria

Feature	TaskCompleteException	CompletionCriteria
Control	LLM decides when done	External criteria
Timing	Explicit action call	Checked after each turn
Use case	Task signals completion	Max iterations, output patterns

Author:

TnsAI Team

See Also:

• CompletionSignal
• Serialized Form

Constructor Summary

Constructors

Constructor	Description
TaskCompleteException(String summary)	Creates a completion exception with just a summary.
TaskCompleteException(String summary, Object result)	Creates a completion exception with summary and result.
TaskCompleteException(String summary, Object result, boolean success, Map<String,Object> metadata)	Creates a completion exception with all parameters.

Method Summary

Modifier and Type	Method	Description
static TaskCompleteException	failed(String summary, String reason)	Creates a failed completion.
Map<String,Object>	getMetadata()	Gets the metadata map.
Object	getMetadataValue(String key)	Gets a specific metadata value.
Object	getResult()	Gets the result data.
<T> T	getResultAs(Class<T> type)	Gets the result as a specific type.
String	getSummary()	Gets the completion summary.
boolean	hasResult()	Checks if result is present.
boolean	isSuccess()	Checks if completion was successful.
String	toString()
static TaskCompleteException	withMetadata(String summary, Map<String,Object> metadata)	Creates a completion with metadata.
static TaskCompleteException	withResult(String summary, Object result)	Creates a successful completion with result.

Methods inherited from class com.tnsai.exceptions.TnsAIException

getContext, getErrorCode, getMaxRetryAttempts, getMessage, getSuggestedRetryDelayMs, getThrownAt, isRetryable, wrap

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

TaskCompleteException

public TaskCompleteException(String summary)

Creates a completion exception with just a summary.

Parameters:

summary - brief description of completion

TaskCompleteException

public TaskCompleteException(String summary,
 Object result)

Creates a completion exception with summary and result.

Parameters:

summary - brief description of completion

result - the result data

TaskCompleteException

public TaskCompleteException(String summary,
 Object result,
 boolean success,
 Map<String,Object> metadata)

Creates a completion exception with all parameters.

Parameters:

summary - brief description of completion

result - the result data

success - whether completion was successful

metadata - additional metadata

Method Details

withResult

public static TaskCompleteException withResult(String summary,
 Object result)

Creates a successful completion with result.

Parameters:

summary - completion summary

result - the result data

Returns:

completion exception

failed

public static TaskCompleteException failed(String summary,
 String reason)

Creates a failed completion.

Parameters:

summary - failure summary

reason - the failure reason

Returns:

completion exception

withMetadata

public static TaskCompleteException withMetadata(String summary,
 Map<String,Object> metadata)

Creates a completion with metadata.

Parameters:

summary - completion summary

metadata - additional metadata

Returns:

completion exception

getSummary

public String getSummary()

Gets the completion summary.

Returns:

brief description of completion

getResult

public Object getResult()

Gets the result data.

Returns:

result object or null

getResultAs

public <T> T getResultAs(Class<T> type)

Gets the result as a specific type.

Type Parameters:

T - expected type

Parameters:

type - the class of expected type

Returns:

typed result or null

isSuccess

public boolean isSuccess()

Checks if completion was successful.

Returns:

true if successful

getMetadata

public Map<String,Object> getMetadata()

Gets the metadata map.

Returns:

immutable metadata map

getMetadataValue

public Object getMetadataValue(String key)

Gets a specific metadata value.

Parameters:

key - the metadata key

Returns:

value or null

hasResult

public boolean hasResult()

Checks if result is present.

Returns:

true if result is not null

toString

public String toString()

Overrides:

toString in class Throwable