@almadar/agent 2.0.0 → 2.0.1

package/dist/tools/execute.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Execute Tool
+ *
+ * Sandboxed shell command execution within a workspace directory.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import type { AuditLog } from '../security/audit-log.js';
+/**
+ * Check if a command contains paths outside the workspace.
+ * Returns an error message if unsafe, null if safe.
+ */
+export declare function validateCommandPaths(command: string, workDir: string): string | null;
+/**
+ * Create an execute tool that runs shell commands in the workspace directory.
+ *
+ * @param workDir   Workspace directory — commands are sandboxed to this path.
+ * @param auditLog  Optional audit chain. When provided, every execution attempt
+ *                  (blocked or successful) is recorded with command, gate
+ *                  classification, exit code, and output length.
+ */
+export declare function createExecuteTool(workDir: string, auditLog?: AuditLog): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    command: z.ZodString;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    timeout?: number | undefined;
+}, {
+    command: string;
+    timeout?: number | undefined;
+}>, {
+    command: string;
+    timeout?: number | undefined;
+}, {
+    command: string;
+    timeout?: number | undefined;
+}, string, "execute">;

package/dist/tools/finish-task.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Finish Task Tool
+ *
+ * Signals the agent has completed the workflow. Automatically combines
+ * orbitals and validates the result.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Create a finish_task tool that signals the agent has completed the workflow.
+ *
+ * Automatically combines orbitals from:
+ * 1. .orbitals/ directory (for kflow-orbitals skill)
+ * 2. domain.txt (for lean skills) - converted to schema via convertDomainToSchema
+ */
+export declare function createFinishTaskTool(workDir: string | undefined): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    summary: z.ZodString;
+    schemaPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    schemaPath?: string | undefined;
+}, {
+    summary: string;
+    schemaPath?: string | undefined;
+}>, {
+    summary: string;
+    schemaPath?: string | undefined;
+}, {
+    summary: string;
+    schemaPath?: string | undefined;
+}, {
+    success: boolean;
+    status: string;
+    message: string;
+    summary: string;
+    autoCombined: boolean;
+    source: "domain" | "orbitals" | undefined;
+    stats: {
+        totalOrbitals: number;
+        totalEntities: number;
+        totalPages: number;
+        totalTraits: number;
+    } | undefined;
+    validation: {
+        valid: boolean;
+        errorCount: number;
+        warningCount: number;
+    } | undefined;
+    designQuality: {
+        propCorrections: number;
+        compositionWarnings: string[];
+    };
+    schemaPath: string | undefined;
+    nextAction: string;
+}, "finish_task">;

package/dist/tools/generate-schema.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Schema Generation Tool (via Structured Output LLM)
+ *
+ * Generates KFlow schemas using OpenAI's structured output mode.
+ * Uses @almadar/llm StructuredOutputClient directly.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Create a tool that generates KFlow schemas using structured output.
+ */
+export declare function createGenerateSchemaTool(): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    userRequest: z.ZodString;
+    suggestedTraits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    suggestedEntities: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    suggestedPages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    suggestedPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    additionalInstructions: z.ZodOptional<z.ZodString>;
+    existingSchema: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    userRequest: string;
+    suggestedTraits?: string[] | undefined;
+    suggestedEntities?: string[] | undefined;
+    suggestedPages?: string[] | undefined;
+    suggestedPatterns?: string[] | undefined;
+    additionalInstructions?: string | undefined;
+    existingSchema?: string | undefined;
+}, {
+    userRequest: string;
+    suggestedTraits?: string[] | undefined;
+    suggestedEntities?: string[] | undefined;
+    suggestedPages?: string[] | undefined;
+    suggestedPatterns?: string[] | undefined;
+    additionalInstructions?: string | undefined;
+    existingSchema?: string | undefined;
+}>, {
+    userRequest: string;
+    suggestedTraits?: string[] | undefined;
+    suggestedEntities?: string[] | undefined;
+    suggestedPages?: string[] | undefined;
+    suggestedPatterns?: string[] | undefined;
+    additionalInstructions?: string | undefined;
+    existingSchema?: string | undefined;
+}, {
+    userRequest: string;
+    suggestedTraits?: string[] | undefined;
+    suggestedEntities?: string[] | undefined;
+    suggestedPages?: string[] | undefined;
+    suggestedPatterns?: string[] | undefined;
+    additionalInstructions?: string | undefined;
+    existingSchema?: string | undefined;
+}, string, "generate_schema">;

package/dist/tools/github.d.ts

@@ -0,0 +1,297 @@
+/**
+ * GitHub Tools for DeepAgent
+ *
+ * LangChain tools that wrap GitHubIntegration operations.
+ * These tools enable the agent to clone repos, create branches, commit, push, and create PRs.
+ */
+import { z } from 'zod';
+/**
+ * GitHub tools configuration
+ */
+export interface GitHubToolsConfig {
+    /** GitHub personal access token */
+    token: string;
+    /** Repository owner (e.g., 'octocat') */
+    owner?: string;
+    /** Repository name (e.g., 'hello-world') */
+    repo?: string;
+    /** Working directory for git operations */
+    workDir: string;
+}
+/**
+ * Create GitHub tools for the agent
+ */
+export declare function createGitHubTools(config: GitHubToolsConfig): {
+    github_clone: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        repoUrl: z.ZodString;
+        branch: z.ZodOptional<z.ZodString>;
+        depth: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        repoUrl: string;
+        branch?: string | undefined;
+        depth?: number | undefined;
+    }, {
+        repoUrl: string;
+        branch?: string | undefined;
+        depth?: number | undefined;
+    }>, {
+        repoUrl: string;
+        branch?: string | undefined;
+        depth?: number | undefined;
+    }, {
+        repoUrl: string;
+        branch?: string | undefined;
+        depth?: number | undefined;
+    }, string, "github_clone">;
+    github_create_branch: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        branchName: z.ZodString;
+        baseBranch: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        branchName: string;
+        baseBranch?: string | undefined;
+    }, {
+        branchName: string;
+        baseBranch?: string | undefined;
+    }>, {
+        branchName: string;
+        baseBranch?: string | undefined;
+    }, {
+        branchName: string;
+        baseBranch?: string | undefined;
+    }, string, "github_create_branch">;
+    github_commit: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        message: z.ZodString;
+        files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        files?: string[] | undefined;
+    }, {
+        message: string;
+        files?: string[] | undefined;
+    }>, {
+        message: string;
+        files?: string[] | undefined;
+    }, {
+        message: string;
+        files?: string[] | undefined;
+    }, string, "github_commit">;
+    github_push: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        branchName: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        branchName: string;
+    }, {
+        branchName: string;
+    }>, {
+        branchName: string;
+    }, {
+        branchName: string;
+    }, string, "github_push">;
+    github_create_pr: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodString;
+        baseBranch: z.ZodString;
+        headBranch: z.ZodString;
+        draft: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        baseBranch: string;
+        title: string;
+        body: string;
+        headBranch: string;
+        draft?: boolean | undefined;
+    }, {
+        baseBranch: string;
+        title: string;
+        body: string;
+        headBranch: string;
+        draft?: boolean | undefined;
+    }>, {
+        baseBranch: string;
+        title: string;
+        body: string;
+        headBranch: string;
+        draft?: boolean | undefined;
+    }, {
+        baseBranch: string;
+        title: string;
+        body: string;
+        headBranch: string;
+        draft?: boolean | undefined;
+    }, string, "github_create_pr">;
+    github_list_issues: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        state: z.ZodOptional<z.ZodEnum<["open", "closed", "all"]>>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        limit?: number | undefined;
+        state?: "open" | "closed" | "all" | undefined;
+        labels?: string[] | undefined;
+    }, {
+        limit?: number | undefined;
+        state?: "open" | "closed" | "all" | undefined;
+        labels?: string[] | undefined;
+    }>, {
+        limit?: number | undefined;
+        state?: "open" | "closed" | "all" | undefined;
+        labels?: string[] | undefined;
+    }, {
+        limit?: number | undefined;
+        state?: "open" | "closed" | "all" | undefined;
+        labels?: string[] | undefined;
+    }, string, "github_list_issues">;
+    github_get_issue: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        issueNumber: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        issueNumber: number;
+    }, {
+        issueNumber: number;
+    }>, {
+        issueNumber: number;
+    }, {
+        issueNumber: number;
+    }, string, "github_get_issue">;
+    github_get_pr_comments: import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        prNumber: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        prNumber: number;
+    }, {
+        prNumber: number;
+    }>, {
+        prNumber: number;
+    }, {
+        prNumber: number;
+    }, string, "github_get_pr_comments">;
+};
+/**
+ * Create GitHub tools as array (for easy spreading into agent tools)
+ */
+export declare function createGitHubToolsArray(config: GitHubToolsConfig): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    repoUrl: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    repoUrl: string;
+    branch?: string | undefined;
+    depth?: number | undefined;
+}, {
+    repoUrl: string;
+    branch?: string | undefined;
+    depth?: number | undefined;
+}>, {
+    repoUrl: string;
+    branch?: string | undefined;
+    depth?: number | undefined;
+}, {
+    repoUrl: string;
+    branch?: string | undefined;
+    depth?: number | undefined;
+}, string, "github_clone"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    branchName: z.ZodString;
+    baseBranch: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    branchName: string;
+    baseBranch?: string | undefined;
+}, {
+    branchName: string;
+    baseBranch?: string | undefined;
+}>, {
+    branchName: string;
+    baseBranch?: string | undefined;
+}, {
+    branchName: string;
+    baseBranch?: string | undefined;
+}, string, "github_create_branch"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    message: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    files?: string[] | undefined;
+}, {
+    message: string;
+    files?: string[] | undefined;
+}>, {
+    message: string;
+    files?: string[] | undefined;
+}, {
+    message: string;
+    files?: string[] | undefined;
+}, string, "github_commit"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    branchName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    branchName: string;
+}, {
+    branchName: string;
+}>, {
+    branchName: string;
+}, {
+    branchName: string;
+}, string, "github_push"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+    baseBranch: z.ZodString;
+    headBranch: z.ZodString;
+    draft: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    baseBranch: string;
+    title: string;
+    body: string;
+    headBranch: string;
+    draft?: boolean | undefined;
+}, {
+    baseBranch: string;
+    title: string;
+    body: string;
+    headBranch: string;
+    draft?: boolean | undefined;
+}>, {
+    baseBranch: string;
+    title: string;
+    body: string;
+    headBranch: string;
+    draft?: boolean | undefined;
+}, {
+    baseBranch: string;
+    title: string;
+    body: string;
+    headBranch: string;
+    draft?: boolean | undefined;
+}, string, "github_create_pr"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    state: z.ZodOptional<z.ZodEnum<["open", "closed", "all"]>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit?: number | undefined;
+    state?: "open" | "closed" | "all" | undefined;
+    labels?: string[] | undefined;
+}, {
+    limit?: number | undefined;
+    state?: "open" | "closed" | "all" | undefined;
+    labels?: string[] | undefined;
+}>, {
+    limit?: number | undefined;
+    state?: "open" | "closed" | "all" | undefined;
+    labels?: string[] | undefined;
+}, {
+    limit?: number | undefined;
+    state?: "open" | "closed" | "all" | undefined;
+    labels?: string[] | undefined;
+}, string, "github_list_issues"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    issueNumber: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    issueNumber: number;
+}, {
+    issueNumber: number;
+}>, {
+    issueNumber: number;
+}, {
+    issueNumber: number;
+}, string, "github_get_issue"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    prNumber: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    prNumber: number;
+}, {
+    prNumber: number;
+}>, {
+    prNumber: number;
+}, {
+    prNumber: number;
+}, string, "github_get_pr_comments">)[];