AgentScript Language Specification

Introduction

AgentScript is an AI-first intermediate language designed to be succinct, expressive, and easily transpilable to TypeScript. It incorporates best practices from contract programming, functional programming, and concurrency to ensure generated code is robust and maintainable.

Syntax

Function Definitions

Functions in AgentScript are defined using the following syntax:

function <name>(<parameters>): <return_type>
  goal: <string>
  backstory: <string>
  requires:
    <constraint>: <string>
    ...
  return: <expression>
  errors:
    <error_name>: <string> when <condition>
    ...
  tests:
    success:
      <input> -> <expected_output>
      ...
    errors:
      <input> -> <expected_error>
      ...
    performance:
      input: <input> -> expect < <time>
      ...

• goal and backstory provide natural language context about the function’s purpose.
• requires defines pre-conditions that must be met by the input.
• return specifies the function body as an expression.
• errors lists expected error conditions and their corresponding messages.
• tests includes test cases categorized into success, error, and performance scenarios.

Pipe Operator

The pipe operator |> is used for function composition:

<value> |> <function1> |> <function2> ...

This is equivalent to <function2>(<function1>(<value>)).

Pattern Matching

Pattern matching is supported using the match keyword:

match (<value>) {
  case <pattern1> -> <result1>
  case <pattern2> -> <result2>
  ...
  default -> <default_result>
}

Patterns can match on values, types, or object structures.

Semantics

Purity and Immutability

By default, functions in AgentScript may mutate local state but should avoid side effects. A stricter mode can be enabled to enforce complete purity and immutability.

Under strict mode:

• Function parameters are immutable.
• Reassignment and mutation are prohibited.
• Functions must be side-effect free.

Type System

AgentScript uses a strict type system to prevent runtime errors. Types are inferred where possible, but can be explicitly annotated.

Some key types:

• Primitives: string, number, boolean, null, undefined
• Arrays: <type>[]
• Objects: { <key>: <type>, ... }
• Functions: (<param_type>, ...) => <return_type>
• Union: <type1> | <type2> | ...

The special type any disables type checking and should be avoided.

Error Handling

Errors in AgentScript are defined as tagged unions and thrown explicitly. The requires block defines pre-conditions that throw errors if not met.

Custom error types are defined in the errors block of a function and thrown using throw <error_name>.

Concurrency

AgentScript has native support for common concurrency patterns:

• Parallel operations using the parallel keyword.
• State machines using the machine block.
• Concurrent effects using effect handlers.

The specifics of these are still being developed.

Transpilation

AgentScript code is transpiled to idiomatic TypeScript for execution. The transpiler performs the following key transformations:

• Translates pipe operators to nested function calls.
• Converts pattern matching to equivalent conditionals.
• Generates type declarations from AgentScript types.
• Converts pre-conditions to runtime checks that throw errors.
• Extracts inline tests to a test framework like Vitest.

Concurrency constructs are transpiled to use appropriate libraries like XState for state machines.

The goal is for the generated TypeScript to be human-readable and maintainable, while still benefiting from AgentScript’s expressiveness and safety features.

Tooling

The AgentScript toolchain includes:

• Language Server: Provides intelligent code completion, type checking, and refactoring.
• Linter: Enforces best practices and detects potential bugs.
• Formatter: Ensures consistent code style.
• Test Runner: Executes inline tests and reports results.
• Bundler: Packages AgentScript code and its dependencies for distribution.

Tooling is designed to integrate smoothly with existing TypeScript workflows and IDEs.

Conclusion

AgentScript is a work in progress proposal, but aims to provide a productive and reliable way to generate TypeScript code using AI. By embedding best practices into the language itself, AgentScript enables developers and AI models to collaborate more effectively.

As the language evolves, this specification will be updated to reflect the latest syntax, semantics, and tooling. Feedback and contributions are welcome!