aif-parser

Reference TypeScript parser for the Agent Instruction Format (AIF) — a plain-text format for expressing executable instructions to autonomous agents, orchestration systems, and automated pipelines.

For the full AIF specification, see AIF Specification v1.0.0.

Install

npm install aif-parser

Quick Start

import { parseAIF } from 'aif-parser'

const result = parseAIF(document)
if (result.valid) {
    console.log(result.ast)
} else {
    result.errors.forEach(e => console.error(e))
}

Error Handling

Use validateAIF to get structured diagnostics:

import { validateAIF } from 'aif-parser'

const [valid, diagnostics] = validateAIF(document)
if (!valid) {
    diagnostics.forEach(d => {
        console.error(`[${d.severity.toUpperCase()}] ${d.message}`)
    })
}

Diagnostics include:

• Structural errors — missing front matter, invalid block syntax, duplicate IDs
• Semantic errors — missing required fields, unknown block references, plaintext credentials
• Warnings — unknown enum values, invalid semver, missing default arms

API

parseAIF(source: string): ParseResult

Parses an AIF document string and returns the AST.

Returns: ParseResult with ast, errors, warnings, and valid fields.

validateAIF(source: string): [boolean, Diagnostic[]]

Validates an AIF document. Returns a tuple of [isValid, diagnostics].

serialiseAIF(doc: Document): string

Serialises a Document AST back to AIF source text.

findBlock(doc: Document, blockId: string): ASTNode | null

Finds a block by its ID.

blocksByType(doc: Document, blockType: string): ASTNode[]

Returns all blocks of a given type.

workflowSteps(doc: Document, workflowId: string): ASTNode[]

Returns the ordered step ASTNodes for a @Workflow.

resolveRef(doc: Document, ref: string): ASTNode | null

Resolves a $ref string to its ASTNode (intra-document only).

Example

---
aif-version: 1.0
id: example-pipeline
title: Example Pipeline
---

@Agent[runner] {
    name:        "Test Runner"
    capabilities: [ test, lint ]
    timeout:     10m
}

@Task[run-tests] {
    title:    "Run test suite"
    agent:    runner
    priority: @Priority::high
    input {
        branch:   String
        coverage: Boolean = true
    }
}

Type Definitions

Document

ASTNode

FieldValue

ParseResult

Diagnostic

SourceLocation

Contributing

Contributions are welcome! Please read the AIF Contributing Guide for details on the specification change process and coding standards.

License

MIT