cog

Part of Alexandrite Software Library - a set of high-quality and performant JavaScript libraries for everyday use.

Overview

asljs-cog is a framework for developing and running automations from composable tasks. A task is one bounded job; tasks run in a shared Context that gives them data, variables, tools, services, a task factory and a task runner, so a task can create and run other tasks and form a workflow.

import { Context,
         DefaultTaskRunner,
         GitTool,
         NodeCommandRunner,
         registerCoreTasks,
         SingletonServiceProvider,
         TaskRegistry }
  from 'asljs-cog';

const registry =
  new TaskRegistry();

registerCoreTasks(registry);

const context =
  new Context(
    { taskFactory: registry,
      taskRunner: new DefaultTaskRunner(),
      serviceProvider: new SingletonServiceProvider(),
      tools:
        [ [ 'git',
            new GitTool(
              new NodeCommandRunner()) ] ] });

const changed =
  await context.run(
    context.createTask<string[]>(
      'get-changed-files',
      { workingDirectory: '/path/to/repo' }));

Scope

• Tasks. A task implements Task<TResult> with an asynchronous run(context). TaskRegistry maps stable names to task creators and keeps each task's description and parameters; DefaultTaskRunner runs a task in a context.
• Built-in tasks. registerCoreTasks registers the agent, Git, build, test, formatting, TODO and envelope tasks, among them a TODO-driven workflow that asks an agent to implement a TODO, then builds, tests and commits.
• Tools. Named adapters for external programs: Git, npm, dotnet, dprint, sfmt, JetBrains cleanupcode, and an agent CLI spoken to over the Agent Client Protocol, Copilot CLI by default.
• Pipelines. A composite task describes a state machine of tasks, gates and ends; runPipeline moves a packet through it, with parallel branches, joins, timers, failure gates and nested composites with data of their own, and records its run as a packet graph. registerPipeline makes a pipeline a task. See Pipeline Vision.
• Services. SingletonServiceProvider creates each service once and disposes it at the end, so a run starts one agent, not one per request.
• Runtime. Node.js, ES modules. The cog command line and the task MCP server are the cog CLI and asljs-cog-mcp packages.

Installation

npm install asljs-cog

NPM Package: asljs-cog

Usage

A task of your own, registered with a stable name, a description and its parameters, and run in the context above:

import { type Context,
         type Task }
  from 'asljs-cog';

class CountChangedFilesTask implements Task<number>
{
  constructor(
    readonly parameters: { workingDirectory: string; }
  )
  {
  }

  async run(
    context: Context
  ): Promise<number>
  {
    const files =
      await context.run(
        context.createTask<string[]>(
          'get-changed-files',
          this.parameters));

    context.logger.debug('%d changed file(s)', files.length);

    return files.length;
  }
}

registry.register(
  'count-changed-files',
  parameters =>
    new CountChangedFilesTask(
      parameters as { workingDirectory: string; }),
  { description: 'count the changed files of a repository',
    parameters:
      [ { name: 'workingDirectory',
          type: 'string',
          position: true } ] });

context.setData(name, value) updates a named shared bucket, and context.getData(name) or context.requireData(name) reads one.

Further reading

• Requirements - tasks, the context, tools, services, the agent and the built-in tasks.

Questions and bugs: asljs/issues.

Related packages

• cog CLI - the cog command over this library.
• asljs-cog-mcp - the asljs-cog-tasks MCP server.
• agents - the ACP session the agent tool speaks to the agent through.
• logging - the loggers tasks report their progress to.

License

MIT License. See LICENSE for details.