Aegis 0.1 reference runtime

.aeg programs run as a closed AST over integers, finite floats, booleans and strings. The runtime uses a dedicated lexer/parser, never Python eval, exec, imports from source, host object traversal, or shell execution. It parses and validates the entire program, including unreachable branches, before requesting input or emitting output.

Agent tools

Call aegis_docs() before writing scripts. It returns language rules and six complete correct example .aeg files, each with its content, purpose, sample input strings and expected output. Examples cover arithmetic, string concatenation, branching, nested conditions, short-circuiting and single/multiple input pauses. These are bundled documentation, independent of the virtual store; the tool takes no filename and reads no host files. Create an example as a virtual file before running it.

create_file(filename="scripts/greet.aeg", content="...") creates a reusable virtual script.
run_ag_file(filename="scripts/greet.aeg") starts a fresh execution.
If its status is input_required, call provide_ag_input(value="text") on the next response. The request includes a one-based index and source line/column. Read the script and its captured output to determine what text to provide; input() has no prompt.
Continue until ok or error. Output is cumulative, including across input pauses. Errors return empty output; output already delivered before a pause cannot be retracted.

Only one program can wait for input. Source is fixed for that run. Completed runs release their environment. Every later invocation starts from scratch. Paused runs are discarded at wake end, including on failure or reaching the response cap. The virtual source file persists and can be run again after a restart.

An input request changes the current wake's limit from five to 20 total model responses, not 20 additional responses and not 20 responses per program. Even an input request in response five enables response six. The cap resets to five next wake. Scripts without input do not extend the wake. Tool calls made in response 20 still run, but cannot cause response 21.

Syntax and semantics

UTF-8, one statement per line, optional final newline, LF or CRLF. Tabs are forbidden. Indent each level by consistently two or four spaces. Blank/comment-only lines do not affect indentation. Blocks must contain a statement.
Names match [a-z][a-z0-9_]*. Keywords and input/print are reserved.
Strings use double quotes and JSON escapes (\n, \t, \", \\, \uXXXX, etc.). Literal Unicode is allowed; invalid Unicode and raw control characters are rejected.
Integers use decimal digits. Floats use a fractional part and/or exponent, such as 3.5, 1e3, 1.5e-2. Leading-dot and trailing-dot floats are not supported.
Statements: name = expression, print(expression), and if expression: with an indented body and optional matching else: body. Assignment has program scope.
input() is a string expression and can appear anywhere an expression is allowed. print is a statement and accepts exactly one value. It emits a newline and spells booleans true/false. Text is captured, never sent to a terminal.
Precedence, high to low: parentheses; unary not/-; right-associative ^; *//; +/-; comparisons; and; or. As specified, -2 ^ 2 is 4. Consecutive unary operators require parentheses. Comparison chaining is rejected.
Numeric operations exclude booleans. Mixed arithmetic promotes int to float; overflow during promotion is an error. Division returns float. Negative integer powers return float; nonnegative integer powers return int. 0 ^ 0 is 1. Zero division, complex results and non-finite values are errors.
+ also concatenates two strings. No string multiplication or implicit conversion.
Equality requires identical types: 1 == 1.0 and true == 1 are false. Ordering accepts same types and compatible int/float pairs; all other mixed ordering fails. Strings compare by Unicode code point; bool ordering is false before true.
Boolean operators require bool operands and short-circuit evaluation. Their skipped expressions are still statically validated, but do not request input or calculate.
Validation tracks types and definite assignment across both branches. A variable assigned in just one branch is unavailable afterward unless assigned beforehand. Branch type unions are allowed only where every possible operand type is valid. Sequential reassignment may change type.

Default bounds

Host code can supply an immutable aegis.Limits to Session or run; source code cannot change limits. These bounds apply across parsing, validation and evaluation:

Resource	Default
UTF-8 source bytes	65,536
Characters per line	2,048
Identifier characters	64
Block/expression nesting	32
Tokens, including structural tokens	8,192
Budgeted operations	20,000
Conservative cumulative allocation accounting	2,000,000 bytes
String / per-input UTF-8 bytes	16,384 / 16,384
Captured output UTF-8 bytes	65,536
Integer magnitude	4,096 bits
Absolute exponent	4,096
Input requests per run	20
Active parse/validate/execute time	1 second

Memory accounting charges source storage, tokens, AST nodes, values, assignments and output. It is cumulative, so a script can exhaust it even if its current live values would fit. Integer multiplication/power and string concatenation check growth before performing the operation. A conservative growth check can reject a borderline value. Nesting and token limits bound parser/validator recursion and AST growth. Time checks occur at bounded operations; time spent waiting for the AI is excluded.

Security boundary and its limits

The interpreter receives only source and explicit input strings. It exposes no host filesystem, networking, process, environment, clock, random, reflection or object APIs. Filenames are virtual dictionary keys, never paths resolved against the machine. Outputs come only from Aegis values; unexpected failures become fixed host_error messages. Structured diagnostics have a category, source line and column and contain no host exception text, traceback, terminal capture or real source filename.

This is an application-level capability boundary, not an absolute OS sandbox. The Python interpreter and trusted host runtime remain part of the trusted computing base. Allocation accounting does not impose a process RSS limit, and timeout checks are cooperative rather than an OS kill timer. No implementation can promise absence of all bugs. Aegis can echo a path or secret explicitly supplied in its source/input; it has no mechanism to discover either from the host. The agent's separately authorized email and web tools are outside this language boundary.

Error categories: syntax_error, indentation_error, name_error, type_error, value_error, limit_error, host_error. File lookup failures and malformed tool requests use the same safe envelopes. Normal results contain only JSON data.