Skip to main content

​
Code Blocks

Tools for managing TypeScript code blocks that run on Val.town/Deno. Code blocks can be called from HAL expressions via the code function and have auto-synced adapters generated for them.

​
Get Code Block

Retrieve a code block’s metadata, code, argument schemas, and version history. When called without an ID, lists code blocks with optional filtering.

​
Parameters

ParameterRequiredDescription
definitionIdNoCode block ID. Omit to list all code blocks
nameNoFilter by name (when listing)
pageNoPage number for pagination

​
Returns

  • Metadata — Name, intent, creation date
  • Code — Full TypeScript source for the selected version
  • Argument schemas — Input and output schemas extracted from the deployed endpoint
  • Versions — List of all versions with publish status
  • Auto-synced adapter ID — The adapter that stays in sync with this code block

​
Create Code Block

Create a new code block with TypeScript source code. The code is deployed to Val.town and an adapter is auto-generated.

​
Parameters

ParameterRequiredDescription
nameYesCode block name
codeYesTypeScript source code
publishNoImmediately publish the first version

​
Code Format

Code blocks must use the @herd-labs/code-blocks-framework package: 
import { initializeHerdCodeBlockServer } from "@herd-labs/code-blocks-framework";

export default initializeHerdCodeBlockServer({
  inputSchema: {
    years: { type: "int256" },
  },
  outputSchema: {
    seconds: { type: "uint256" },
  },
  handler: async ({ years }) => {
    const seconds = BigInt(years) * 365n * 24n * 60n * 60n;
    return { seconds: seconds.toString() };
  },
}).fetch;
Set publish=true to make the code block immediately usable in actions. Otherwise, publish later via the update tool.

​
Update Code Block

Update a code block’s metadata and/or TypeScript code. Code changes trigger redeployment and schema re-extraction.

​
Parameters

ParameterRequiredDescription
definitionIdYesCode block ID
nameNoNew name
intentNoNew intent/description
codeNoNew TypeScript source code
publishNoPublish the latest unpublished draft
When code is provided: if the latest version is an unpublished draft, it’s updated in-place; otherwise a new draft version is created.

​
Delete Code Block

Delete a code block and its auto-synced adapter.

​
Parameters

ParameterRequiredDescription
definitionIdYesCode block ID
Deletion fails if the auto-synced adapter is imported by other actions or adapters.

​
Execute Code Block

Run a code block with given arguments. Uses the test branch (safe for iteration).

​
Parameters

ParameterRequiredDescription
definitionIdYesCode block ID
codeIdNoSpecific version ID (defaults to latest)
argsYesInput arguments matching the code block’s schema

​
Returns

  • Result — Output values from the code block
  • Logs — Console output from execution (useful for debugging)

​
How Code Blocks Work in HAL

Once created, code blocks are callable in HAL expressions via the code function: 
["coerce", {
  "type": { "seconds": "uint256" },
  "value": ["code", { "args": { "years": "years" }, "id": "definitionId:codeVersionId" }]
}]
Each code block has an auto-synced adapter that updates automatically when the code is published. This adapter can be imported into actions like any other adapter.

​
Next Steps

Actions & Adapters

Use code blocks in actions

Evaluation

Test your code blocks in expressions