From b61af35c7e8f4d083df14235b4f33a2ba1424c4a Mon Sep 17 00:00:00 2001 From: Lakshman Patel Date: Wed, 29 Jul 2026 13:21:06 +0530 Subject: [PATCH 1/2] feat: add composio/cognee types and proto schema Add shared cross-repo contracts for composio and cognee integration: - ComposioTool, ComposioToolResult, ComposioCredential - CogneeQAEntry, CogneeTraceEntry, CogneeFeedbackEntry, CogneeSkillRunEntry - AgentSkill, AgentSkillChain (agentskills.io spec) - Proto schema: proto/hawk/contracts/v1/composio_cognee.proto Stdlib-only, zero hawk-eco dependencies. --- proto/hawk/contracts/v1/composio_cognee.proto | 158 ++++++++++++++++ types/composio_cognee.go | 168 ++++++++++++++++++ 2 files changed, 326 insertions(+) create mode 100644 proto/hawk/contracts/v1/composio_cognee.proto create mode 100644 types/composio_cognee.go diff --git a/proto/hawk/contracts/v1/composio_cognee.proto b/proto/hawk/contracts/v1/composio_cognee.proto new file mode 100644 index 0000000..0e167fd --- /dev/null +++ b/proto/hawk/contracts/v1/composio_cognee.proto @@ -0,0 +1,158 @@ +syntax = "proto3"; + +package hawk.contracts.v1; + +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +option go_package = "github.com/GrayCodeAI/hawk-core-contracts/gen/go/hawk/contracts/v1;contractsv1"; + +// ComposioToolScope defines the scope at which a composio tool operates. +enum ComposioToolScope { + COMPOSITOOL_SCOPE_UNSPECIFIED = 0; + COMPOSITOOL_SCOPE_READ = 1; + COMPOSITOOL_SCOPE_WRITE = 2; + COMPOSITOOL_SCOPE_ACTION = 3; +} + +// ComposioTool mirrors types.ComposioTool — a tool available from the +// composio platform. Params is arbitrary JSON (google.protobuf.Struct). +message ComposioTool { + string name = 1; + string description = 2; + ComposioToolScope scope = 3; + bool auth_required = 4; + google.protobuf.Struct params = 5; + repeated string tags = 6; + string category = 7; +} + +// ComposioToolResult mirrors types.ComposioToolResult — the result of +// executing a composio tool. +message ComposioToolResult { + bool success = 1; + google.protobuf.Struct data = 2; + string error = 3; +} + +// ComposioCredential mirrors types.ComposioCredential — an API credential +// for a connected service. Value is never serialized in the proto. +message ComposioCredential { + string id = 1; + string service_name = 2; + string type = 3; + string scope = 4; + google.protobuf.Timestamp expires_at = 5; + map metadata = 6; +} + +// CogneeEntryType identifies a structured memory entry kind. +enum CogneeEntryType { + COGNEE_ENTRY_TYPE_UNSPECIFIED = 0; + COGNEE_ENTRY_TYPE_QA = 1; + COGNEE_ENTRY_TYPE_TRACE = 2; + COGNEE_ENTRY_TYPE_FEEDBACK = 3; + COGNEE_ENTRY_TYPE_SKILL_RUN = 4; +} + +// CogneeQAEntry mirrors types.CogneeQAEntry — a Q&A conversation turn +// with optional feedback. +message CogneeQAEntry { + CogneeEntryType type = 1; + string question = 2; + string answer = 3; + string context = 4; + string feedback_text = 5; + int32 feedback_score = 6; + repeated string used_graph_ids = 7; + string session_id = 8; + string project = 9; + string source_agent = 10; + google.protobuf.Timestamp timestamp = 11; +} + +// CogneeTraceEntry mirrors types.CogneeTraceEntry — a single step in an +// agent's execution trace. +message CogneeTraceEntry { + CogneeEntryType type = 1; + string origin_function = 2; + string status = 3; + string method_params = 4; + string method_return_value = 5; + string memory_query = 6; + string memory_context = 7; + string error_message = 8; + bool generate_feedback = 9; + string session_id = 10; + string project = 11; + string source_agent = 12; + google.protobuf.Timestamp timestamp = 13; +} + +// CogneeFeedbackEntry mirrors types.CogneeFeedbackEntry — feedback +// attached to an existing QA entry. +message CogneeFeedbackEntry { + CogneeEntryType type = 1; + string target_node_id = 2; + string feedback_text = 3; + int32 feedback_score = 4; + string project = 5; + string session_id = 6; + string source_agent = 7; + google.protobuf.Timestamp timestamp = 8; +} + +// CogneeSkillRunEntry mirrors types.CogneeSkillRunEntry — an execution +// record for a skill. +message CogneeSkillRunEntry { + CogneeEntryType type = 1; + string skill_name = 2; + string skill_version = 3; + string params = 4; + string result = 5; + string status = 6; + int64 duration_ms = 7; + string error = 8; + string project = 9; + string session_id = 10; + string source_agent = 11; + google.protobuf.Timestamp timestamp = 12; +} + +// AgentSkillCategory defines the category of an agent skill. +enum AgentSkillCategory { + AGENT_SKILL_CATEGORY_UNSPECIFIED = 0; + AGENT_SKILL_CATEGORY_ENGINEERING = 1; + AGENT_SKILL_CATEGORY_OPS = 2; + AGENT_SKILL_CATEGORY_TESTING = 3; + AGENT_SKILL_CATEGORY_SECURITY = 4; + AGENT_SKILL_CATEGORY_DEVTOOLS = 5; + AGENT_SKILL_CATEGORY_WORKFLOW = 6; +} + +// AgentSkillChain mirrors types.AgentSkillChain — declares relationships +// between skills. +message AgentSkillChain { + repeated string after = 1; + repeated string before = 2; + repeated string conflicts = 3; + repeated string enhances = 4; +} + +// AgentSkill mirrors types.AgentSkill — a skill conforming to the +// agentskills.io specification. +message AgentSkill { + string name = 1; + string description = 2; + string version = 3; + string author = 4; + string license = 5; + AgentSkillCategory category = 6; + bool auto_invoke = 7; + string compatibility = 8; + string allowed_tools = 9; + repeated string agents = 10; + string invoke = 11; + repeated string refs = 12; + AgentSkillChain chain = 13; +} diff --git a/types/composio_cognee.go b/types/composio_cognee.go new file mode 100644 index 0000000..be1b1a1 --- /dev/null +++ b/types/composio_cognee.go @@ -0,0 +1,168 @@ +// Package types provides shared cross-repo contracts for the hawk-eco +// platform. This file adds types for composio and cognee integration, +// enabling SDKs and engines to share a common vocabulary for: +// - Composio tool metadata (discovery, search, execution) +// - Cognee structured memory entries (QA, trace, feedback, skill run) +// - Composio credential management +package types + +import "time" + +// --- Composio Types --- + +// ComposioToolScope defines the scope at which a composio tool operates. +type ComposioToolScope string + +const ( + ComposioScopeReadOnly ComposioToolScope = "read" + ComposioScopeWrite ComposioToolScope = "write" + ComposioScopeAction ComposioToolScope = "action" +) + +// ComposioTool represents a tool available from the composio platform. +type ComposioTool struct { + Name string `json:"name"` + Description string `json:"description"` + Scope ComposioToolScope `json:"scope"` + AuthRequired bool `json:"auth_required"` + Params map[string]interface{} `json:"params"` + Tags []string `json:"tags"` + Category string `json:"category"` +} + +// ComposioToolResult is the result of executing a composio tool. +type ComposioToolResult struct { + Success bool `json:"success"` + Data map[string]interface{} `json:"data,omitempty"` + Error string `json:"error,omitempty"` +} + +// ComposioCredential holds an API credential for a connected service. +type ComposioCredential struct { + ID string `json:"id"` + ServiceName string `json:"service_name"` + Type string `json:"type"` // "oauth", "api_key", "password" + Value string `json:"-"` // never serialize + Scope string `json:"scope,omitempty"` + ExpiresAt time.Time `json:"expires_at,omitempty"` + Metadata map[string]string `json:"metadata,omitempty"` +} + +// IsExpired reports whether the credential has expired. +func (c ComposioCredential) IsExpired() bool { + if c.ExpiresAt.IsZero() { + return false + } + return time.Now().After(c.ExpiresAt) +} + +// --- Cognee Structured Entry Types --- + +// CogneeEntryType identifies a structured memory entry kind. +type CogneeEntryType string + +const ( + CogneeEntryQA CogneeEntryType = "qa" + CogneeEntryTrace CogneeEntryType = "trace" + CogneeEntryFeedback CogneeEntryType = "feedback" + CogneeEntrySkillRun CogneeEntryType = "skill_run" +) + +// CogneeQAEntry captures a Q&A conversation turn with optional feedback. +type CogneeQAEntry struct { + Type CogneeEntryType `json:"type"` + Question string `json:"question"` + Answer string `json:"answer"` + Context string `json:"context,omitempty"` + FeedbackText string `json:"feedback_text,omitempty"` + FeedbackScore *int `json:"feedback_score,omitempty"` + UsedGraphIDs []string `json:"used_graph_element_ids,omitempty"` + SessionID string `json:"session_id,omitempty"` + Project string `json:"project"` + SourceAgent string `json:"source_agent,omitempty"` + Timestamp time.Time `json:"timestamp"` +} + +// CogneeTraceEntry captures a single step in an agent's execution trace. +type CogneeTraceEntry struct { + Type CogneeEntryType `json:"type"` + OriginFunction string `json:"origin_function"` + Status string `json:"status"` + MethodParams string `json:"method_params,omitempty"` + MethodReturnValue string `json:"method_return_value,omitempty"` + MemoryQuery string `json:"memory_query,omitempty"` + MemoryContext string `json:"memory_context,omitempty"` + ErrorMessage string `json:"error_message,omitempty"` + GenerateFeedback bool `json:"generate_feedback_with_llm"` + SessionID string `json:"session_id"` + Project string `json:"project"` + SourceAgent string `json:"source_agent,omitempty"` + Timestamp time.Time `json:"timestamp"` +} + +// CogneeFeedbackEntry attaches feedback to an existing QA entry. +type CogneeFeedbackEntry struct { + Type CogneeEntryType `json:"type"` + TargetNodeID string `json:"target_node_id"` + FeedbackText string `json:"feedback_text"` + Score *int `json:"feedback_score,omitempty"` + Project string `json:"project"` + SessionID string `json:"session_id,omitempty"` + SourceAgent string `json:"source_agent,omitempty"` + Timestamp time.Time `json:"timestamp"` +} + +// CogneeSkillRunEntry persists an execution record for a skill. +type CogneeSkillRunEntry struct { + Type CogneeEntryType `json:"type"` + SkillName string `json:"skill_name"` + SkillVersion string `json:"skill_version,omitempty"` + Params string `json:"params,omitempty"` + Result string `json:"result,omitempty"` + Status string `json:"status"` + DurationMs int64 `json:"duration_ms,omitempty"` + Error string `json:"error,omitempty"` + Project string `json:"project"` + SessionID string `json:"session_id,omitempty"` + SourceAgent string `json:"source_agent,omitempty"` + Timestamp time.Time `json:"timestamp"` +} + +// --- Agent Skills Spec (agentskills.io) --- + +// AgentSkillCategory defines the category of an agent skill. +type AgentSkillCategory string + +const ( + SkillCategoryEngineering AgentSkillCategory = "engineering" + SkillCategoryOps AgentSkillCategory = "ops" + SkillCategoryTesting AgentSkillCategory = "testing" + SkillCategorySecurity AgentSkillCategory = "security" + SkillCategoryDevtools AgentSkillCategory = "devtools" + SkillCategoryWorkflow AgentSkillCategory = "workflow" +) + +// AgentSkillChain declares relationships between skills. +type AgentSkillChain struct { + After []string `json:"after,omitempty"` + Before []string `json:"before,omitempty"` + Conflicts []string `json:"conflicts,omitempty"` + Enhances []string `json:"enhances,omitempty"` +} + +// AgentSkill represents a skill conforming to the agentskills.io specification. +type AgentSkill struct { + Name string `json:"name"` + Description string `json:"description"` + Version string `json:"version"` + Author string `json:"author"` + License string `json:"license"` + Category AgentSkillCategory `json:"category,omitempty"` + AutoInvoke bool `json:"auto_invoke,omitempty"` + Compatibility string `json:"compatibility,omitempty"` + AllowedTools string `json:"allowed_tools,omitempty"` + Agents []string `json:"agents,omitempty"` + Invoke string `json:"invoke,omitempty"` + Refs []string `json:"refs,omitempty"` + Chain AgentSkillChain `json:"chain,omitempty"` +} From ec4f593686518dd45b7082fc2e44709a3c5d5ec0 Mon Sep 17 00:00:00 2001 From: Lakshman Patel Date: Wed, 29 Jul 2026 13:32:03 +0530 Subject: [PATCH 2/2] fix: correct proto enum prefix and gofumpt formatting - Fix ComposioToolScope enum values to use COMPOSIO_TOOL_SCOPE_ prefix (buf lint requirement) - Apply gofumpt formatting to types/composio_cognee.go --- proto/hawk/contracts/v1/composio_cognee.proto | 8 ++-- types/composio_cognee.go | 38 +++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/proto/hawk/contracts/v1/composio_cognee.proto b/proto/hawk/contracts/v1/composio_cognee.proto index 0e167fd..5e9a875 100644 --- a/proto/hawk/contracts/v1/composio_cognee.proto +++ b/proto/hawk/contracts/v1/composio_cognee.proto @@ -9,10 +9,10 @@ option go_package = "github.com/GrayCodeAI/hawk-core-contracts/gen/go/hawk/contr // ComposioToolScope defines the scope at which a composio tool operates. enum ComposioToolScope { - COMPOSITOOL_SCOPE_UNSPECIFIED = 0; - COMPOSITOOL_SCOPE_READ = 1; - COMPOSITOOL_SCOPE_WRITE = 2; - COMPOSITOOL_SCOPE_ACTION = 3; + COMPOSIO_TOOL_SCOPE_UNSPECIFIED = 0; + COMPOSIO_TOOL_SCOPE_READ = 1; + COMPOSIO_TOOL_SCOPE_WRITE = 2; + COMPOSIO_TOOL_SCOPE_ACTION = 3; } // ComposioTool mirrors types.ComposioTool — a tool available from the diff --git a/types/composio_cognee.go b/types/composio_cognee.go index be1b1a1..96edb60 100644 --- a/types/composio_cognee.go +++ b/types/composio_cognee.go @@ -14,9 +14,9 @@ import "time" type ComposioToolScope string const ( - ComposioScopeReadOnly ComposioToolScope = "read" - ComposioScopeWrite ComposioToolScope = "write" - ComposioScopeAction ComposioToolScope = "action" + ComposioScopeReadOnly ComposioToolScope = "read" + ComposioScopeWrite ComposioToolScope = "write" + ComposioScopeAction ComposioToolScope = "action" ) // ComposioTool represents a tool available from the composio platform. @@ -70,17 +70,17 @@ const ( // CogneeQAEntry captures a Q&A conversation turn with optional feedback. type CogneeQAEntry struct { - Type CogneeEntryType `json:"type"` - Question string `json:"question"` - Answer string `json:"answer"` - Context string `json:"context,omitempty"` - FeedbackText string `json:"feedback_text,omitempty"` - FeedbackScore *int `json:"feedback_score,omitempty"` - UsedGraphIDs []string `json:"used_graph_element_ids,omitempty"` - SessionID string `json:"session_id,omitempty"` - Project string `json:"project"` - SourceAgent string `json:"source_agent,omitempty"` - Timestamp time.Time `json:"timestamp"` + Type CogneeEntryType `json:"type"` + Question string `json:"question"` + Answer string `json:"answer"` + Context string `json:"context,omitempty"` + FeedbackText string `json:"feedback_text,omitempty"` + FeedbackScore *int `json:"feedback_score,omitempty"` + UsedGraphIDs []string `json:"used_graph_element_ids,omitempty"` + SessionID string `json:"session_id,omitempty"` + Project string `json:"project"` + SourceAgent string `json:"source_agent,omitempty"` + Timestamp time.Time `json:"timestamp"` } // CogneeTraceEntry captures a single step in an agent's execution trace. @@ -135,11 +135,11 @@ type AgentSkillCategory string const ( SkillCategoryEngineering AgentSkillCategory = "engineering" - SkillCategoryOps AgentSkillCategory = "ops" - SkillCategoryTesting AgentSkillCategory = "testing" - SkillCategorySecurity AgentSkillCategory = "security" - SkillCategoryDevtools AgentSkillCategory = "devtools" - SkillCategoryWorkflow AgentSkillCategory = "workflow" + SkillCategoryOps AgentSkillCategory = "ops" + SkillCategoryTesting AgentSkillCategory = "testing" + SkillCategorySecurity AgentSkillCategory = "security" + SkillCategoryDevtools AgentSkillCategory = "devtools" + SkillCategoryWorkflow AgentSkillCategory = "workflow" ) // AgentSkillChain declares relationships between skills.