Skip to main content

​
Overview

Retrieves the current workflow session for a project, including status, progress, and metadata. Essential for monitoring build/deployment progress and getting session IDs for bilt_send_message.
Sessions are automatically created when you send your first message to a project. Use this tool to get the session ID before calling bilt_send_message.

​
Parameters

​
session_id
string
Specific session ID to query
  • Format: UUID
  • Optional: If omitted, returns current/most recent session
  • Example: "550e8400-e29b-41d4-a716-446655440000"
​
project_id
string
Project to get session for (if session_id not provided)
  • Format: UUID
  • Example: "660e8400-e29b-41d4-a716-446655440001"

​
Response

​
session_id
string
required
Unique session identifier
​
project_id
string
required
Associated project ID
​
status
string
required
Current workflow statusValues:
  • "idle" - No active workflow
  • "pending" - Queued, waiting to start
  • "running" - Actively processing
  • "completed" - Successfully finished
  • "failed" - Error occurred
​
progress
object
Progress information (when available)
​
created_at
string
required
ISO 8601 timestamp of session creation
​
updated_at
string
required
ISO 8601 timestamp of last activity

​
Example Usage

​
Get Current Session

{}

​
Get Specific Session

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Status Values Explained

idleNo workflow running. Ready to accept new messages.

pendingWorkflow queued. Will start shortly.

runningActively building/deploying. Check progress field.

completedWorkflow finished successfully.

failedError occurred. Check messages for details.

pausedWorkflow paused. Can resume with bilt_resume_workflow.

​
Common Patterns

​
Pattern 1: Get Session ID Before Sending Message

Agent workflow:
1. User: "Add a login page to my app"
2. Agent calls bilt_get_session()
3. Agent receives session_id
4. Agent calls bilt_send_message(session_id, "Add login page")

​
Pattern 2: Monitor Build Progress

// Pseudo-code
async function waitForCompletion(sessionId) {
  while (true) {
    const session = await bilt_get_session({ session_id: sessionId });
    
    if (session.status === 'completed') {
      return 'Build complete!';
    }
    
    if (session.status === 'failed') {
      throw new Error('Build failed');
    }
    
    if (session.progress) {
      console.log(`Progress: ${session.progress.percentage}%`);
      console.log(`Step: ${session.progress.current_step}`);
    }
    
    await sleep(2000); // Poll every 2 seconds
  }
}

​
Pattern 3: Check if Workflow is Running

Before sending a new message:

Agent workflow:
1. Call bilt_get_session()
2. If status === "running": "A workflow is already in progress"
3. If status === "idle": Proceed with new message
4. If status === "failed": Offer to retry or fix

​
Best Practices

Never hardcode session IDs. Always fetch the current one:
// ✅ Good
const { session_id } = await bilt_get_session();
await bilt_send_message({ session_id, message: "..." });

// ❌ Bad
await bilt_send_message({ 
  session_id: "hardcoded-id", 
  message: "..." 
});
When monitoring progress, don’t poll too frequently:
// ✅ Good: 2-5 second intervals
await sleep(2000);

// ❌ Too aggressive: 100ms intervals
await sleep(100);
Respect the current workflow state:
const session = await bilt_get_session();

switch (session.status) {
  case 'running':
    // Wait or offer to cancel
    break;
  case 'failed':
    // Offer to retry or debug
    break;
  case 'idle':
    // Safe to start new workflow
    break;
}
When available, display progress updates:
Agent: "Building your app... (65% complete)"
Agent: "Current step: Building components"
Agent: "Estimated time remaining: 2 minutes"

​
Error Handling

{
  "error": "Invalid or expired API key"
}

bilt_send_message

Send workflow instructions

bilt_get_messages

View workflow history

bilt_cancel_workflow

Stop running workflow

​
Next Steps

After getting session:
  1. Send instructions - Use bilt_send_message
  2. View logs - Use bilt_get_messages
  3. Resume if paused - Use bilt_resume_workflow
  4. Cancel if needed - Use bilt_cancel_workflow